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": "done"}

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 and a command'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 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 event is a plain message, and nothing is replayed after a reconnect (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.