Events
The event topics, what each carries, who receives it and which need a subscription.
The frame #
Events are evt {topic, d}. A surface addresses one agent with ag, or omits it to reach every attached agent. The hub adds s, the surface the event is about, when it relays.
{"t":"evt","topic":"ui","s":"s1","d":{"rev":14}}Topics #
| topic | payload d |
sent when | needs |
|---|---|---|---|
ui |
{rev} |
The UI tree changed. At most once per 100 ms. It carries only the new revision: call observe for the delta. |
sub, and the observe scope |
state |
{name, patch} |
An exposed piece of app state changed. patch is an RFC 7396 merge patch against the value this agent last received. |
sub, and the observe scope |
nav |
{url, title} |
The page navigated. | sub, and the observe scope |
user |
{kind}: override, pause or resume |
The person used the page while an agent was driving it (override), or pressed Pause or Resume. |
sub |
user |
{kind:"level", level}, {kind:"rule", a, d}, {kind:"relay", on} |
The person set something for this one agent in the panel: the level of its grant, a rule for one action (d is null when the rule was removed), or whether it hears the other agents in the chat. |
nothing |
grant |
{kind}: revoked or expired |
The grant ended: the person pressed Stop or refused three prompts in a row, or the hub ended it (revoked), or the grant reached its expiry or went idle (expired). |
nothing |
grant |
{kind:"scopes", scopes} |
The person switched scopes of the grant off or back on. scopes are those now in force. The grant goes on. |
nothing |
surface |
{kind, surface}: added, gone or changed |
A surface connected, disconnected, or changed its listing. | nothing |
chat |
a message: {id, from, text, ts, to?} |
Someone said something in the page's chat room that this agent may hear: the person, or another agent where the room relays those. Never the agent's own. | the chat scope |
Subscribing #
Agents opt into ui, state, user and nav with sub {topics}, and out with unsub. Both answer with the topics now subscribed. grant, surface and chat events need no subscription, and neither do the user events level, rule and relay.
await handle.subscribe(['ui', 'state', 'user']);
handle.on('ui', ({ rev }) => {});
handle.on('grant', (e) => {}); // { kind: 'revoked' | 'expired' } or { kind: 'scopes', scopes }
handle.on('user', (e) => {}); // also { kind: 'level', level }, { kind: 'rule', a, d }, { kind: 'relay', on }
handle.on('chat', (message) => {}); // needs no subscribe
client.on('surface', ({ kind, surface }) => {});Who gets what #
The hub relays an event only to live grants with the scope its topic needs: ui, state and nav need observe, and user goes to every live grant.
surface events come from the hub alone:
addedandgonego to every agent that may attach to that surface;changedgoes only to agents holding a grant on it.
An agent hears about a surface only if its credential may attach to it. Without a live grant that includes observe, the SurfaceInfo in the event is reduced: url is the origin and title is the app's name.
What a surface may not send #
A grant event from a surface is acted on by its kind and never relayed as it came: revoked ends grants, scopes changes the scopes of one grant, and any other kind is dropped. The user events level and rule say what the person set for one agent: the hub checks and records them, and then tells that agent alone. A surface event sent by a surface is dropped, as is an event with an unknown topic.
A chat event is never broadcast. A surface sends it once for each agent that is to hear the message, and the hub relays it to that grant alone, while the grant holds chat, in an event built from the checked fields, with the sender's name as the hub gave it. The hub takes no event from an agent, so an agent cannot send one.
Within a version, receivers ignore unknown event topics.
State patches #
A merge patch cannot express a property whose value is null, so such a property reads as absent. A state that differs from the last one only in null properties, or not at all, produces no event.