Control Protocol

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:

TypeMeaningNotable fields
window-createdA window was created.session, window, pty_id, title
window-closedA window was removed.session, window, pty_id
window-exitA window's shell process exited.session, window, pty_id
window-retitledA window's title or name changed.session, window, title
window-focusedA window became the focused window.session, window, pty_id
window-movedA window moved to another workspace.session, window, pty_id, workspace
window-minimizedA window was minimized.session, window, pty_id
window-restoredA minimized window was restored.session, window, pty_id
workspace-switchedThe session's current workspace changed.session, workspace
workspace-renamedA workspace's name was set, changed or cleared. title is the new name, absent when the name was cleared.session, workspace, title
layout-changedThe 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-stateA window's agent state changed, whichever tier changed it. A pane ceasing to be an agent reports none.session, window, pty_id, state
agent-seenThe 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-messageA 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
outputA window produced output (activity signal only; the raw bytes still flow over the binary stream).session, window, pty_id, bytes
bellA window rang the terminal bell.session, window, pty_id
notificationA 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-changedA terminal mode toggled (for example alt-screen).session, window, mode, enabled
session-createdA session was created.session
session-closedA session was terminated.session
session-labelledA 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-changedA 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
gapSome events were not delivered to this connection. reason says why (see below). A gap has no seq.reason, dropped, boot_id
attentionAn 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-changedA 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-removedgit 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
promptA 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-startedA shell with OSC 133 marks started a command. cmdline is cut to 512 bytes, with likely secrets masked.session, window, pty_id, cmdline
command-finishedThat 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-activityOne 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
transcriptThe 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-upgradedA 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
transferA 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-progressA 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-fileOne 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-claimedA 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-finishedA task card was marked done. window is the pane that held it, empty when none did.session, window, task
task-changedA 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-dispatchA 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-awakeThe 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-eventWhat 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-surfaceA 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-created exactly as new-window does.
  • 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-retitled fires for an explicit rename (the set-window verb 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 higher seq before streaming live. 0 replays everything the daemon still holds.
  • boot_id (optional, needs after_seq): the boot id after_seq came with.
  • hosts (optional): also deliver the agent-state, session-created and session-closed events this daemon relays from its linked hosts, each with host set, 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, window or pane, and only an attention or host-changed event. 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:

reasonMeaningWhat follows
evictedEvents after after_seq have already left the ring.The events the ring still holds, then live.
boot_changedboot_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_retainedThe 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-output matches pattern against the target window's captured content. Checked once immediately, then re-checked as the window produces output.
  • window-exit resolves when the target window's shell process exits. The result carries exit_code (-1 when a signal stopped the process) and signal when 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-idle resolves after the target window produces no output for idle milliseconds.
  • session-exists resolves when a session named session exists.
  • agent-state resolves when a window's agent state becomes one of the states named in until (checked once immediately, so a pane already in the state resolves at once). With window it watches that pane and fails with window_not_found if the pane closes mid-wait; without window any window in the session matches, which is the "tell me when any agent here needs input" shape. With any_session any window in any session matches, including sessions created during the wait; passing session or window with it, or using it with another condition, is invalid_params. The result names the session, the window and the state that matched.
  • agent-message resolves when a message arrives. With window it watches that inbox, matches the first unread message already there, and fails with window_not_found if the inbox's window closes mid-wait. Without window it matches any message left in the session after the wait began. thread narrows either form to one thread. The result names the message (message_id, kind, from, subject) and never carries its body: read it with read-agent-messages.
  • command-finished resolves when a shell that marks its commands with OSC 133 finishes one. With window it watches that pane: the next command to finish after the wait starts, or with command_seq N the first once the pane has finished more than N, which matches at once when that already happened. Read N from list-windows before starting the command and the wait cannot miss it. It fails with pty_not_found if the pane's shell exits. Without window any pane in the session matches, and command_seq is invalid_params. The result carries window, cmdline, exit_code (omitted when the shell sent none), duration_ms and command_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"}}

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