OpenMax
Free Trial

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 sync all belong to the host's connection. With OpenMax the adapter gets realtime: "off", and openMaxSharedRealtime hands 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 one reconnected each 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; with storage: "localStorage" and a device id that reads back after it is written, it also acknowledges sync (paging first when there is has_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:

  1. opening a conversation;
  2. switching back to a conversation opened before;
  3. the realtime connection coming back, i.e. the adapter emits reconnected;
  4. the page returning to the foreground.

The rules of gap-fill:

  • One at a time per conversation. If another gap-fill moment or a messages signal 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. loadThreadSince is called repeatedly until the returned ChatThreadSincePage has hasNewer: 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 messages signal 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_seq order.
  • Dedup. A frame whose run_id + run_seq was already applied is dropped, so the server may resend safely.
  • Gaps. When a run_seq arrives more than 1 ahead of the last one applied, the client holds the frame, fetches that run's events after the last applied number by run_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 seq and do not move the watermark.
  • Ending. After RUN_FINISHED or RUN_ERROR a run accepts no more events. If the agent goes silent for too long, the server ends the run with a RUN_ERROR on 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.loadRunEvents with its run_id, from the last applied run_seq; the ending event (RUN_FINISHED or RUN_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.