Realtime and sync
How server changes reach the client — realtime signals, the agent event frame, and seq and watermarks, time fields, gap-fill moments, dedup, gaps, reconnects, run snapshots and fetching a run's events.
Realtime and sync
Messages and agent runs share one realtime connection and are caught up at the same moments. The only difference is the sequence number: messages use seq within a conversation, run events use run_seq within a run.
Realtime signals
The SDK owns the realtime connection. It connects with the endpoint, token and client id from the host's inboundDelivery, and turns every frame from the server into a signal for the components. Your app does not open a connection of its own.
| Signal | Meaning | What the components do |
|---|---|---|
{ kind: "messages", conversationId } |
The conversation has new messages | Call loadThreadSince from the highest seq they have |
{ kind: "reaction", conversationId, messageId, reactorId, code, added, changeSeq? } |
Someone added or removed a reaction | Update that message's reactions |
{ kind: "messageChanged", conversationId, messageId, change, changeSeq?, recalledByRole? } |
Someone edited (edited) or recalled (recalled) a message, moderation removed it (deleted), or someone answered a card (card) |
edited: if the message is in the loaded window, fetch the new text by id with loadMessage; card: the same fetch, but only the card fields are taken (a result already shown is never cleared); recalled: show it as recalled (recalledByRole: "admin", the frame's recalled_by_role, shows "An admin recalled a message" without names; otherwise the sender's name); deleted: remove it, with no "recalled" placeholder |
{ kind: "read", conversationId, memberId, readUntilSeq } |
Someone's read position moved forward | Update read receipts |
{ kind: "delivery", conversationId, ackUntilSeq } |
The conversation's delivery position moved forward | Update delivery state |
{ kind: "card", conversationId, messageId, fields } |
A card's content or result (card_state) changed |
Update that card |
{ kind: "reconnected" } |
The connection is back | Catch up again; the connection status returns to connected |
{ kind: "connected" } (optional) |
The connection opened for the first time | Refetch the conversation list and catch up open conversations once; presence and profile reads are kept |
{ kind: "disconnected" } Planned |
The connection dropped and is reconnecting | Connection status becomes reconnecting; see ChatInboundDisconnectedSignal |
{ kind: "typing", conversationId, memberId, active } |
Someone started or stopped typing (ChatInboundTypingSignal); may be the current user (the server sends it back to the sender too) |
The message area does nothing; the Chat SDK's conversation header updates the typing indicator (filtering out the current user when reading); after active is true, no new one within 6 seconds counts as stopped |
{ kind: "presence", memberId, status, lastSeenAt? } (the Chat SDK's own, not passed to @openmaxai/chat components; see ChatSdkPresenceSignal) |
A member went online or offline (org-wide) | The Chat SDK's conversation header updates the peer's presence in an Agent DM; on reconnect it drops the recorded presence first, then re-reads the member profile once |
After every successful reconnect, push { kind: "reconnected" } to tell the UI the connection is back; when it drops, push { kind: "disconnected" }. Never on heartbeats. Planned The messages signal carries no message body; bodies always come from loadThreadSince. With createChatHost, the endpoint is wsUrl.
Your own reactions, edits and recalls do not wait for a signal: the UI changes first, and on success the host may return the number of the change (changeSeq in ChatMessageChangeResult), which lets the message store recognise the push for the same change when it arrives. Changes by others arrive as messageChanged: it names the message and the kind of change but carries no body, so without loadMessage an edit by someone else shows only when the window is loaded again. The changeSeq on reaction and messageChanged is the number in the server's change log; frames from older servers have none, and then it is left out.
Changes others made to existing messages while you were offline or away are caught up from the change log: when the host provides loadChangesSince and getMessagesByIds and its windows carry headChangeSeq, the catch-up on reconnect and on switching back to a conversation goes on, after the new messages, to catch up on changes (hosts built by createChatHost do this). When a push's change number skips ahead, changes are caught up 1.5 seconds later; signals that never reach the store (an edit or recall outside the window, a failed fetch) carry no number there, so the change watermark stops before them until the next push or catch-up.
Host-forwarded signals are transitional: while an app still holds its own connection during migration, it turns that connection's frames into the same signals and forwards them through inboundDelivery.subscribe(onSignal), and the SDK does not open a second connection, because two connections with the same device id overwrite each other's sync position. This forwarding is only for an app that still holds its own connection during migration and has not wired up openMaxSharedRealtime; once it uses the borrowing port, it stops forwarding. A demo host (isMock() is true) also pushes signals through subscribe; see Connect your own backend.
Who owns the page's one connection comes in two forms:
- The host already has its own connection: connecting, the ticket, the device id, reconnecting and recovering when the page returns to the foreground, and acknowledging
syncall belong to the host's connection. With OpenMax the adapter getsrealtime: "off", andopenMaxSharedRealtimehands the raw frames from that connection to the SDK. Decoding and translating frames stays in the adapter package, in one copy; the SDK opens no connection and acknowledges nothing, and gets onereconnectedeach time the connection opens. - No connection of its own (the usual external integration): give
wsUrl, and the adapter exchanges the ticket, connects and reconnects with backoff itself; withstorage: "localStorage"and a device id that reads back after it is written, it also acknowledgessync(paging first when there ishas_more), and with the default"memory"it does not.
Use the first form when your app's own connection also serves things outside chat (presence, notifications, Agent activity): the chat SDK borrows it instead of opening a second one, and the connection stays your app's realtime module.
Sequence numbers
| Messages | Run events Planned | |
|---|---|---|
| Number | seq: increases from 1 within a conversation, no repeats |
run_seq: within a run, 0 for the queued frame, then 1, 2, … for the agent's events |
| Persistent? | Yes, messages are stored by the backend | No, run events are transient and only pushed; only the final reply takes a seq as a message |
| Ordered within | One conversation | One run (subagent invocations' events are part of it and share its run_seq sequence); no order between runs |
| Gaps filled by | loadThreadSince from the watermark |
On a gap, fetching the run's events; at moments such as opening a conversation, a run snapshot |
The agent_event frame
Planned Our extension
Run events are pushed on the chat's own WebSocket in a new frame, agent_event, so authentication, observers and multi-device delivery follow the chat's rules. The envelope holds our own fields, which have no counterpart in AG-UI 1.0; event holds one AG-UI 1.0 event, forwarded without adding or removing fields (AG-UI event objects allow no extra members, which is why all our own information lives in the envelope):
{
"type": "agent_event",
"id": "f_01J9Z3",
"timestamp": 1759590000123,
"payload": {
"conversation_id": "c_123",
"agent_member_id": "m_agent",
"run_id": "r_456",
"run_seq": 3,
"trigger_message_id": "msg_789",
"protocol_version": "1.0",
"permissions": { "cancel": true },
"event": {
"type": "TOOL_CALL_START",
"toolCallId": "t_1",
"toolCallName": "web_search",
"parentMessageId": "msg_789"
}
}
}
type, id and timestamp work as on the chat's other frames, and so do the remaining envelope fields. * marks a field present on every frame; the others may be absent:
payload field |
Description |
|---|---|
conversation_id |
Filled by the backend from the run_id binding; equals the event's threadId. Absent for runs not bound to a conversation (Agent panel only) |
agent_member_id* |
The agent (member id) the run belongs to |
run_id* |
Run id; equals the event's runId |
run_seq* |
Sequence number within the run: 0 for the queued frame, then 1, 2, … for the agent's events |
queued |
Only on the frame with run_seq 0, with the value true: the run is queued. That frame has no event |
trigger_message_id |
The message that triggered the run; absent for runs with no trigger message, such as scheduled jobs |
protocol_version* |
The AG-UI version of event: "1.0" |
permissions |
What the recipient of this frame may do with the run, such as { "cancel": true }. The server fills it per recipient, so two people may get different values for the same run. Absent means nothing is allowed |
event |
The AG-UI 1.0 event object, forwarded without adding or removing fields; only the queued frame has none |
When the event carries threadId or runId, they must match the envelope's conversation_id (for a run not bound to a conversation, the agent thread id the backend issued) and run_id; a frame where they differ is dropped. Clients ignore event types and fields they do not recognize, without an error. A subagent's events carry subagentRunId; the envelope adds no field for it.
The host turns this frame into a ChatAgentEventSignal and pushes it through the same subscribe callback as the other signals; see Connect your own backend.
Time
Planned
There is one rule: a point in time keeps the encoding of the data it belongs to, and times added for agent runs are integer milliseconds since the Unix epoch.
| Field | Encoding | Why |
|---|---|---|
timestamp on the agent_event frame |
Integer milliseconds | Same as timestamp on the chat's other frames |
startedAt / endedAt on ChatAgentRun and on tool calls |
Integer milliseconds | New for agent runs, so the rule above applies |
timestamp on every AG-UI event |
An integer; we require milliseconds Our extension | AG-UI 1.0 makes it an integer without fixing the unit, and every SDK uses milliseconds in practice |
Interrupt.expiresAt (phase 2) |
An ISO 8601 string, such as "2026-10-05T10:00:00Z" |
AG-UI 1.0's convention |
A card's expires_at (phase 2) |
An ISO 8601 string | Maps one to one to Interrupt.expiresAt, and matches the card's created_at and result_at |
The UI computes durations from the envelope's timestamp and the order of arrival, not from the optional timestamp inside AG-UI events.
Gap-fill
Planned
The planned message store fills gaps from the watermark at four moments, so neither you nor the adapter decides when:
- opening a conversation;
- switching back to a conversation opened before;
- the realtime connection coming back, i.e. the adapter emits
reconnected; - the page returning to the foreground.
The rules of gap-fill:
- One at a time per conversation. If another gap-fill moment or a
messagessignal arrives while a conversation is filling, the store waits for that run to finish and then fills once more from the new watermark; it never sends two requests at once. - The server says when to stop.
loadThreadSinceis called repeatedly until the returnedChatThreadSincePagehashasNewer: false, or, when it returns an array, until the array is empty. - At most 10 rounds. If the server still says there is more after 10 rounds, the store loads the latest window once. When it connects to the in-memory window (the peer kept sending so every round had something new, but there is no real gap), it is appended after the window and the rows being read stay put. When it does not connect, the user was away too long and the gap is too big: the store drops the conversation's in-memory window, swaps in the latest window and continues from there; older messages are fetched when the user scrolls up.
- No filling into a window that does not reach the latest. When the window was loaded around a message, or scrolling up unloaded its newer end, a
messagessignal only records that there are new messages (for the "new messages" prompt) and does not fill them into the window; once the window reaches the latest, gap-fill works as usual.
Without loadThreadSince there is no gap-fill, and missed messages appear only when the conversation is reloaded. At the same four moments the store also loads a run snapshot (agentRuns.loadActiveRuns) and reconciles runs that ended.
Run event ordering and gaps
Planned
- Strict order within a run. Clients apply events in
run_seqorder. - Dedup. A frame whose
run_id+run_seqwas already applied is dropped, so the server may resend safely. - Gaps. When a
run_seqarrives more than 1 ahead of the last one applied, the client holds the frame, fetches that run's events after the last applied number byrun_id(agentRuns.loadRunEvents), then continues. Runs bound to a conversation and runs that are not are filled the same way. - No watermark. Run events take no conversation
seqand do not move the watermark. - Ending. After
RUN_FINISHEDorRUN_ERRORa run accepts no more events. If the agent goes silent for too long, the server ends the run with aRUN_ERRORon its behalf, so the UI never stays on "Working" or "Queued". Our extension
Dedup, ordering, filling gaps and deciding when to load snapshots all happen in the shared layer (@openmaxai/chat-store); hosts and adapters only translate frames into signals.
Run snapshots
Planned Our extension
When a conversation is opened (including by a member who was just added, or an observer), and at the four gap-fill moments above, the client loads the run snapshot through agentRuns.loadActiveRuns: every unfinished run in the conversation (queued ones included), each with its envelope fields and all its events so far (each with its run_seq). The client feeds snapshot events and live frames through the same entry point, dedupes by run_seq, and from then on applies only higher numbers.
When the Agent panel opens, it loads a different snapshot (agentRuns.loadAgentRuns): every unfinished run of that agent, including runs not bound to a conversation. The endpoint shapes are in Connect your own backend.
Finished runs are not in the snapshot. The final reply links to its run through metadata.run_id.
Runs missing from a snapshot
The frame that ends a run may be exactly the one missed while disconnected, and a snapshot only returns runs that have not ended, so with snapshots alone the UI would stay on "Working" forever. The rule:
- For a run the store still has as unfinished that is missing from a freshly loaded snapshot, call
agentRuns.loadRunEventswith itsrun_id, from the last appliedrun_seq; the ending event (RUN_FINISHEDorRUN_ERROR) comes back with it. - Both the conversation snapshot and the Agent panel snapshot are reconciled this way; for runs not bound to a conversation this is the only way.
- If the run cannot be fetched (it does not exist, or the current user may not see it), remove it from the store rather than leave it on "Working".
Fetching a run's events
Our extension
The server keeps every event of every run, not just a summary. agentRuns.loadRunEvents returns one run's envelope fields and events by run_id, whether or not the run has ended. It has three uses: filling run_seq gaps, reconciling runs missing from a snapshot, and expanding a finished run to show its tool steps after a reload or on another device (the message store loads it on demand when you expand). The endpoint shape is in Connect your own backend.
Multiple tabs and devices
Every device and every tab of the same user receives the same frames. In phase 1 each tab connects and fills gaps on its own; with IndexedDB on, only the tab holding the single-tab lock writes device data, and the other tabs use memory. In phase 2 one leader tab holds the connection and the others share it.
With realtime: "off" no connection is opened, so new messages and card results from others do not appear on their own.
