# Events and waiting

URL: https://tuios.dev/docs/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](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/protocol-verbs.md). The [Protocol Verbs](https://tuios.dev/docs/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.

| Param       | Type      | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------- | --------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session`   | string    |          |         | Only 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `window`    | string    |          |         | Only deliver events about this window id. Omit for every window.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `types`     | \[]string |          |         | Only 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`. |
| `queue`     | int       |          | `256`   | Buffered events before the stream marks a gap. A size above 4096 is lowered to 4096.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `after_seq` | int       |          |         | Resume: 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_id`   | string    |          |         | The 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `hosts`     | bool      |          | `false` | Also 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 field | Type   | Description                                                                                                                         |
| ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `seq`        | int    | The 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_id`    | string | Random id of this daemon start. Keep it with the seq, and pass both back to resume.                                                 |
| `replayed`   | int    | With after\_seq only: how many events are replayed before the live stream.                                                          |

```json
{"id":1,"verb":"subscribe","params":{"session":"work","types":["window-created","window-closed"]}}
```

```json
{"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.

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

## `wait-for` (Added in v0.8.0)

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

| Param         | Type   | Required | Default  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------- | ------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `condition`   | string |          |          | Condition to wait for. One of `session-exists`, `window-output`, `window-exit`, `window-idle`, `agent-state`, `agent-message` or `command-finished`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `session`     | string |          |          | Session 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `window`      | string |          |          | Window id or name. Omit to target the focused window.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `any_session` | bool   |          | `false`  | For 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `pattern`     | string |          |          | Regular expression, required by window-output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `source`      | string |          | `recent` | Which buffer window-output matches against. The default includes scrollback, so output that has already scrolled past still matches. One of `visible` or `recent`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `new`         | bool   |          | `false`  | For 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `idle`        | int    |          | `500`    | Milliseconds of silence that count as idle, for window-idle.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `until`       | string |          |          | Agent 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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `thread`      | int    |          |          | Narrow agent-message to one thread. Pass any message id in the thread. A thread the ring holds nothing from never matches.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `command_seq` | int    |          |          | For 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `timeout`     | int    |          | `30000`  | Milliseconds to wait before failing with the timeout code, at most 86400000 (24 hours). The wait also ends when the caller closes the connection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `select`      | string |          |          | A 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. |
| `every`       | bool   |          | `false`  | With 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 field | Type   | Description                                                                                                                                                       |
| ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `condition`  | string | The condition that matched.                                                                                                                                       |
| `window`     | string | The window that matched, for a condition about a window.                                                                                                          |
| `exit_code`  | int    | For 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. |
| `signal`     | int    | For window-exit: the signal that ended the process. Omitted when it exited on its own.                                                                            |
| `new`        | bool   | For window-output: true when the wait matched only output written after it started.                                                                               |

```json
{"id":1,"verb":"wait-for","params":{"condition":"window-output","session":"work","pattern":"done","timeout":10000}}
```

```json
{"id":1,"verb":"wait-for","params":{"condition":"agent-state","session":"work","until":"needs_input,idle"}}
```

```json
{"id":1,"verb":"wait-for","params":{"condition":"agent-message","session":"work","window":"$TUIOS_PANE_ID"}}
```

```json
{"id":1,"verb":"wait-for","params":{"condition":"agent-message","session":"work","window":"$TUIOS_PANE_ID","thread":12}}
```

```json
{"id":1,"verb":"wait-for","params":{"condition":"agent-state","any_session":true,"until":"needs_input"}}
```

```json
{"id":1,"verb":"wait-for","params":{"condition":"command-finished","session":"work","window":"build","command_seq":4,"timeout":600000}}
```

```json
{"id":1,"verb":"wait-for","params":{"condition":"agent-state","select":"group:fan/add-retry","until":"idle,done","every":true}}
```

```json
{"id":1,"verb":"wait-for","params":{"condition":"window-output","session":"work","window":"build","pattern":"BUILD OK","new":true}}
```
