Envelope
Every event on the stream is one JSON object with exactly three fields. It names what changed and how; it never carries the changed data itself.
{"entity": "task", "id": 4916, "action": "created"}
Fields
| Field | Type | Meaning |
|---|---|---|
entity | string | The kind of item that changed, such as task or node. The event catalog lists them all. |
id | integer or string | Which item changed. A task's, a command's, a Live Cast event's and a pipeline event's (the project's) id are integers; the others are string ids, or 0 (below). Each catalog entry shows an example. 0 means a whole list changed. |
action | string | What happened, such as created, deleted or a task's new state. Each entity's actions are in the catalog. |
When id is 0
Some events name no single item. They carry id 0 and mean "something in this list changed — refetch
the list". Worktree, runner and agent session events always do this, and a node or agent account event sometimes
does.
Each catalog entry says what its id holds.
What is never sent
- No extra fields. There is no timestamp, no actor, no item data and no old or new value. Refetch the item to read its current state.
- No organization or server fields. Jaah removes its own routing fields before an event leaves the server, so you never see which organization or which Jaah server an event came from.
- No event
id:or event name. Every change is a plainmessage, and nothing is replayed after a reconnect. The only named event is thekeepalive, which is not an envelope (see Connection).
Handling new values
Jaah may add entities and actions. Ignore any entity or action your client does not know rather than
treating it as an error, and treat every event as a hint to refetch rather than as the change itself.