Realtime Sync

Agent applications produce high-volume live data. A naive “persist every delta and replay all of it” design eventually becomes slow and can freeze the UI.

Three representations

Raw Log            exact provider evidence
Live Stream        short-lived/coalesced deltas for current UX
Historical Model   compact messages/activity/queryable state

They have different jobs and should not be forced into one representation.

Snapshot + subscription

A client opens a Task workspace by obtaining authoritative current state, then receiving bounded updates.

For reconnect:

• small sequence gap → replay/batch bounded updates;
• large gap → return a fresh snapshot;
• cursor ahead of server → treat as invalid and rehydrate;
• subscribe before/during snapshot handoff so events are not lost in the race;
• buffer and drain to the captured head before declaring LIVE.

Exact protocol will be implemented after the first UI vertical slice; these are the invariants.

Coalescing

Never make React publish/render once per historical token delta. Group replay updates and fold them before publishing new UI state. Live markdown may update at a human-useful cadence rather than provider-chunk cadence.

Pagination

Activity, raw logs, comments, and other potentially large histories are paged. The client does not request all history just because it is local.

Connection health versus sync health

A socket can remain connected while one subscription dies. Therefore expose separate state:

Connection: DISCONNECTED | CONNECTING | CONNECTED
Sync: HYDRATING | LIVE | STALE | DEGRADED

Actions relying on freshness should reconcile authoritative state when necessary rather than trusting an indefinitely stale projection.

Derived state

The UI may derive “3 active agents” or “needs attention,” but authoritative state remains in the core. Projections should have explicit dependencies and should not rely on accidental processing order.