Event stream
Event stream: 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.
Event stream
The daemon can push events instead of a caller polling. A connection that issues
the subscribe verb is turned into a long-lived event stream; every other
connection never receives events. Each event is one JSON line carrying a
daemon-global monotonic seq, the daemon's boot_id, a type, and the fields
relevant to that type. Two subscribers always see the same seq for the same
event.
boot_id is a random id the daemon picks each time it starts. A restarted
daemon numbers events from 1 again, so a seq only identifies an event
together with the boot_id it came with. Keep both if you plan to resume.
A live upgrade (daemon-upgrade) keeps the boot_id, the numbering and the replay ring, so a subscriber the upgrade dropped resumes with after_seq as from any other disconnect.
Event types:
| Type | Meaning | Notable fields |
|---|---|---|
window-created | A window was created. | session, window, pty_id, title |
window-closed | A window was removed. | session, window, pty_id |
window-exit | A window's shell process exited. | session, window, pty_id |
window-retitled | A window's title or name changed. | session, window, title |
window-focused | A window became the focused window. | session, window, pty_id |
window-moved | A window moved to another workspace. | session, window, pty_id, workspace |
window-minimized | A window was minimized. | session, window, pty_id |
window-restored | A minimized window was restored. | session, window, pty_id |
workspace-switched | The session's current workspace changed. | session, workspace |
workspace-renamed | A workspace's name was set, changed or cleared. title is the new name, absent when the name was cleared. | session, workspace, title |
layout-changed | The panes on a workspace sit differently: a pane opened, closed, moved, was minimized, zoomed or resized, or the session changed size. Call list-windows to read the new rectangles. Sent only to a subscription that names it in types, and not kept for replay. | session, workspace |
agent-state | A window's agent state changed, whichever tier changed it. A pane ceasing to be an agent reports none. | session, window, pty_id, state |
agent-seen | The person looked at a pane whose agent finished a turn they had not seen (action seen), or marked it unread again (action unread). The agent state does not change. list-agents' finished_unread reads the same fact. | session, window, action |
agent-message | A message was left in the session's ring. window is the recipient, or empty for a session-wide notice. Read the message itself with read-agent-messages. | session, window |
output | A window produced output (activity signal only; the raw bytes still flow over the binary stream). | session, window, pty_id, bytes |
bell | A window rang the terminal bell. | session, window, pty_id |
notification | A window sent a desktop notification with OSC 9, OSC 777 or OSC 99. Each text field is capped at 512 bytes. For a pane attributed to a harness the notification may also move its agent state; see AGENT_STATE.md. | session, window, pty_id, title, body |
mode-changed | A terminal mode toggled (for example alt-screen). | session, window, mode, enabled |
session-created | A session was created. | session |
session-closed | A session was terminated. | session |
session-labelled | A session's display name was set, changed or cleared, by set-session-name or any other route. title is the new display name, absent when it was cleared. A rename (rename-session) raises session-closed and session-created instead. | session, title |
client-session-changed | A daemon connection attached, detached or switched sessions. session is the session entered or left. attached is true when entering and false when leaving, including a disconnect while attached. A rename sends attached: true with the new name to each client in the session. | client_id, pid, session, attached |
gap | Some events were not delivered to this connection. reason says why (see below). A gap has no seq. | reason, dropped, boot_id |
attention | An Inbox item opened, changed or closed. action is open, update or close, and attention is the item as list-attention returns it. On close the item carries closed: resolved, seen, read, dismissed, answered, superseded, window_closed, session_closed, evicted, host_removed, agents_disabled (the person turned the agent features off) or snoozed (the person snoozed it; it opens again with the same id). An answered item also carries answer and answered_by; the close of a linked host's item never reads answered here. session and window are the item's, so the usual filters apply. An item of a linked host also sets host, and a subscriber that filters on a session, window or pane does not get it unless it subscribed with hosts. | session, window, host, action, attention |
host-changed | A linked host's link changed state, or what it holds changed: its sessions, windows or agents. List the hosts again to see what. See Following linked hosts. | host, status |
worktree-removed | git removed a worktree that tuios made: by remove-worktree, or by the undo of a setup or a delegation that did not start. path is the folder that is gone. session is the worktree's session, which may be gone too. A plugin hook on worktree.removed runs on it, with data.path. | session, path |
prompt | A shell that marks its commands with OSC 133 shows its prompt after anything else: at start, or after a command. A prompt drawn again changes nothing and raises nothing. | session, window, pty_id |
command-started | A shell with OSC 133 marks started a command. cmdline is cut to 512 bytes, with likely secrets masked. | session, window, pty_id, cmdline |
command-finished | That command finished. exit_code is absent when the shell sent no status; a prompt with no finish mark ends the command that way. command_seq counts the pane's finished commands. | session, window, pty_id, cmdline, exit_code, duration_ms, command_seq |
agent-activity | One entry of an agent pane's activity ring, as agent-activity returns it. Opt-in: only a subscription whose types names it receives it. Not replayed on a resume. | session, window, entry |
transcript | The transcript that a pane is joined to grew, or the entry a Pi session has selected changed. Read it again with agent-transcript. cursor is the cursor that a read to the end returns now. When you hold that cursor, there is nothing new. An event for a document or for a Pi session carries no cursor: read with the cursor of your last reply. The event carries nothing from the file. It fires at most once for each read the daemon makes, after the 150 ms debounce. Opt-in: only a subscription whose types names it receives it. Not replayed on a resume. | session, window, cursor |
daemon-upgraded | A live upgrade replaced the daemon's image. Raised once, by the image that took the panes over. title is the build the panes came from, body the build that has them now. state is upgraded, fallback when the new binary could not take them and the previous one did, or recovered when the new image died before it was up and the handoff's keeper started the previous binary in its place, under a new daemon pid. No hook runs for it. | title, body, state |
transfer | A copy the daemon runs (see Files and transfers) changed. action is created, state, ended or removed, and transfer is its row as transfer-list returns it. removed says a copy that ended left the list, by transfer-clear or 30 minutes after it ended, and carries its last row. A state is said once per change; a folder copy going between running and verifying for each file is not a change. A copy the daemon takes back from its journal at start says state once. | action, transfer |
transfer-progress | A copy's row while its bytes move, at most four a second per copy. Opt-in: only a subscription whose types names it receives it. Not replayed on a resume. | action (progress), transfer |
transfer-file | One file of a copy ended. action and file.state are done (copied and checked), same (there already with the same bytes), skipped (there and different, left as it was), conflict (made there during the copy, left as it was) or failed. file has id, pane, rel, state, sha256, code and error. Opt-in: only a subscription whose types names it receives it. Not replayed on a resume. | action, file |
task-claimed | A pane took a task card. task is the card's row as list-tasks gives it, and window the pane that took it. See Task verbs. | session, window, task |
task-finished | A task card was marked done. window is the pane that held it, empty when none did. | session, window, task |
task-changed | A task card was added, staged, blocked, unblocked, released, attached, detached or removed (action). An attach or a detach carries the attachment's name in reason. A release tuios made on its own carries reason: pane closed, agent left or restart; a stage move it made on its own carries the fact (see Task verbs); a block carries its reason too. removed carries the card's last row. | session, action, reason, task |
task-dispatch | A board's dispatch mode or a switch changed, or dispatch stopped on its own (action stopped, reason such as 3 failures in a row or usage limit reported by claude-code). dispatch is the whole status as get-task-dispatch gives it. It names no session. | action, reason, dispatch |
keep-awake | The daemon took or dropped its hold that keeps the machine awake, the number of working agent panes changed while keep_awake is agents, or keep_awake changed. mode is off, on or agents, state is held or released, working counts the working agent panes on this machine, and reason says why the machine could not be held awake, when it could not. See get-keep-awake. It names no session. | mode, state, working, reason |
tml-event | What a person did on a TML surface that its owner hears: an emit action in the document, or the close, which is the surface's last event. tml has surface, name (the emit's name, or close), value (absent when null), reason (on a close: closed, program or dismissed) and version. window is the TML window. Opt-in: only a subscription whose types names it receives it, and a tml-open with events gets the events of its own surface. | tml |
tml-surface | A TML surface opened, changed or closed, for a client that draws it from verbs (guios), which gets no attach pushes. tml_surface has surface, title, version, doc_version, ops (the JSON Patch on the state that made version from version - 1, when a patch did and it is at most 64 KiB) and closed. A client that holds version - 1 applies ops; any other reads the surface with tml-get, which a changed doc_version also asks for. window is the TML window. Opt-in, and not kept for replay: a resume over one is marked with a gap |
What fires when
A mutation reaches the daemon's canonical state by one of two routes. Either the daemon mutates its own state (every headless mutation, and the ones it owns even with a client attached), or an attached TUI performs the mutation and syncs the result back. Both routes converge on the same state, and the window lifecycle events are derived from that convergence by diffing the state before and after it, so:
- Every window lifecycle event fires exactly once per mutation, with the same payload fields and the same relative ordering, whether or not a client is attached. There is no separate "headless only" set of events.
- Lifecycle events fire for mutations a human drives from the TUI, not just
for ones a control-plane verb requested. Creating a window with the keyboard
raises
window-createdexactly asnew-windowdoes. - The PTY-driven events (
output,bell,notification,mode-changed,window-exit) hang off the PTY rather than off window state, so they have always fired on both routes and are unaffected.
Ordering within a single mutation is stable: closes, then creates, then
per-window changes (window-retitled, window-moved,
window-minimized/window-restored), then workspace-renamed, then
session-labelled, then workspace-switched, then window-focused. Focus comes last because it is usually a consequence of an
earlier event in the same batch, so a consumer building a model from the stream
already knows about the window being focused by the time it is told to focus it.
Two cases are worth stating plainly because they are easy to guess wrong:
window-retitledfires for an explicit rename (theset-windowverb or the TUI's rename) and, separately, when the shell changes its own title via an OSC escape sequence. The shell-driven case is reported by the PTY, not by the state diff, so a shell retitling itself raises the event once, not twice.- A change that is not a lifecycle change raises nothing. Window geometry, z-order, and alt-screen flags move constantly as a TUI renders and re-tiles; none of them produce events, so an attached client does not flood the stream.
Restoring a session (daemon cold start, or tuios resurrect) raises
session-created followed by a window-created for each restored window, since
from a subscriber's point of view those windows come into existence at that
moment. A plain subscribe carries what happens from the subscription onward,
and the ack's seq is the baseline. Use list-windows to establish initial
state, then follow the stream. A subscriber that reconnects can ask for what it
missed with after_seq (see "Resuming a stream" below).
subscribe
Open the event stream on this connection.
Params:
session(optional): only events from this session. Omit it for events from every session. This is unlike most verbs, where an omitted session means the most recently active one.window(optional): only events about this window id. The filter compares window ids, so a window name matches nothing.types(optional): event types to include; empty means all.queue(optional): per-connection queue size; defaults to 256. A size above 4096 is lowered to 4096.after_seq(optional): resume. Replay the retained events with a higherseqbefore streaming live.0replays everything the daemon still holds.boot_id(optional, needsafter_seq): the boot idafter_seqcame with.hosts(optional): also deliver theagent-state,session-createdandsession-closedevents this daemon relays from its linked hosts, each withhostset, and letsessionandwindowmatch events of other machines. Without it, an event about another machine reaches only a subscriber that names no session, window or pane, and only anattentionorhost-changedevent. See Following linked hosts.
Request:
{"id": 1, "verb": "subscribe", "params": {"session": "work", "types": ["output", "bell"]}}Ack response (the stream begins after this line):
{"id": 1, "result": {"type": "subscribed", "seq": 42, "boot_id": "9f2c41d07a3e8b65"}}Subsequent lines are events, for example:
{"seq": 43, "type": "output", "session": "work", "window": "1f3c...", "pty_id": "9ab2...", "bytes": 64, "boot_id": "9f2c41d07a3e8b65", "time": 1737200000000000000}A second subscribe on the same connection is rejected with invalid_request.
Resuming a stream
The daemon keeps the last 4096 events in a replay ring, apart from output
events, which fire on every PTY read and would push everything else out within
seconds, and agent-activity and transcript events, which fire on every
tool call of every agent. A subscriber that kept the seq of the last event it read, and the
boot_id that came with it, can reconnect and pass both:
{"id": 1, "verb": "subscribe", "params": {"types": ["agent-state"], "after_seq": 118, "boot_id": "9f2c41d07a3e8b65"}}The ack then carries replayed, the number of events that follow before the
live stream:
{"id": 1, "result": {"type": "subscribed", "seq": 131, "boot_id": "9f2c41d07a3e8b65", "replayed": 3}}Every replayed event has a seq above after_seq and at or below the ack's
seq, and every live event has a higher one, so no event is delivered twice.
The replay honours the same session, window and types filter as the live
stream.
When the replay cannot be everything the caller missed, a gap marker comes
first. Read current state again after a gap (list-agents, list-windows)
rather than assuming you saw every change:
reason | Meaning | What follows |
|---|---|---|
evicted | Events after after_seq have already left the ring. | The events the ring still holds, then live. |
boot_changed | boot_id names another daemon start, or no boot_id was passed and after_seq is above anything this daemon has assigned. The numbers are not comparable. | Live events only. |
not_retained | The filter admits output events, or names agent-activity, and at least one such event was published after after_seq. Neither is ever replayed. | The retained events, then live. Leave output and agent-activity out of types for an exact replay. |
Passing this daemon's own boot_id with an after_seq it has not reached yet
is refused with invalid_params, and so is boot_id without after_seq.
Slow subscriber policy
Each subscribed connection has a bounded queue. When it is full the daemon drops the event and counts the drop rather than blocking; the next event delivered to that connection is preceded by a gap marker:
{"type": "gap", "dropped": 12, "reason": "overflow", "boot_id": "9f2c41d07a3e8b65"}so the connection learns it fell behind (the seq values also jump). One slow
reader never stalls the daemon or any other subscriber. A client that reconnects
after an overflow can resume from the last seq it read and get the dropped
events back from the ring, as long as they were not output events and have
not been evicted.
unsubscribe
Close this connection's event stream. Params: none.
{"verb": "unsubscribe"}Response: {"result": {"type": "unsubscribed"}}. Closing the connection also
tears the stream down.
wait-for
Block until a condition matches, then return a wait_result; return a timeout
error if the condition does not match in time. This is sugar over a short-lived
subscription and replaces a caller's capture-pane poll loop.
Params: condition (required), session, window, pattern (regex, for
window-output), source (visible or the default recent/scrollback content,
for window-output), idle (quiet-period milliseconds, for window-idle;
default 500), until (agent state names, comma-separated, for agent-state),
thread (any message id in a thread, to narrow agent-message to that
thread), any_session (bool, for agent-state only: watch every session and
take no session or window), command_seq (for command-finished with a
window), select (a selector, 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), every (bool,
with select: match only when at least one pane matches and all of them are in
an until state, and answer with them in panes), timeout (milliseconds;
default 30000, at most 86400000, which is 24 hours).
A wait ends when its caller closes the connection. It does not wait for its timeout then.
Conditions:
window-outputmatchespatternagainst the target window's captured content. Checked once immediately, then re-checked as the window produces output.window-exitresolves when the target window's shell process exits. The result carriesexit_code(-1 when a signal stopped the process) andsignalwhen a signal stopped it. Both are omitted when the status is not known, such as for a window on another machine. An older client ignores them.window-idleresolves after the target window produces no output foridlemilliseconds.session-existsresolves when a session namedsessionexists.agent-stateresolves when a window's agent state becomes one of the states named inuntil(checked once immediately, so a pane already in the state resolves at once). Withwindowit watches that pane and fails withwindow_not_foundif the pane closes mid-wait; withoutwindowany window in the session matches, which is the "tell me when any agent here needs input" shape. Withany_sessionany window in any session matches, including sessions created during the wait; passingsessionorwindowwith it, or using it with another condition, isinvalid_params. The result names thesession, thewindowand thestatethat matched.agent-messageresolves when a message arrives. Withwindowit watches that inbox, matches the first unread message already there, and fails withwindow_not_foundif the inbox's window closes mid-wait. Withoutwindowit matches any message left in the session after the wait began.threadnarrows either form to one thread. The result names the message (message_id,kind,from,subject) and never carries its body: read it withread-agent-messages.command-finishedresolves when a shell that marks its commands with OSC 133 finishes one. Withwindowit watches that pane: the next command to finish after the wait starts, or withcommand_seqN the first once the pane has finished more than N, which matches at once when that already happened. Read N fromlist-windowsbefore starting the command and the wait cannot miss it. It fails withpty_not_foundif the pane's shell exits. Withoutwindowany pane in the session matches, andcommand_seqisinvalid_params. The result carrieswindow,cmdline,exit_code(omitted when the shell sent none),duration_msandcommand_seq.
Request:
{"id": 1, "verb": "wait-for", "params": {"condition": "window-output", "session": "work", "pattern": "build succeeded", "timeout": 60000}}Response on match:
{"id": 1, "result": {"type": "wait_result", "condition": "window-output", "matched": true, "window": "", "pattern": "build succeeded"}}Response on timeout:
{"id": 1, "error": {"code": "timeout", "message": "timed out waiting for output matching build succeeded"}}Verbs: Other verbs
Verbs: Other verbs: part of the Control Protocol of TUIOS.
Protocol Verbs
Every verb of the TUIOS control protocol, with its arguments, its reply and an example.
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.