@abloatai/ablo 0.3.0

package/dist/sync/SyncWebSocket.d.ts

@@ -0,0 +1,663 @@
+/**
+ * SyncWebSocket - Manages WebSocket connection to Go sync engine
+ *
+ * Handles:
+ * - WebSocket lifecycle (connect, reconnect, disconnect)
+ * - Delta reception and processing
+ * - Multi-tab support
+ * - Automatic reconnection with exponential backoff
+ */
+import { EventEmitter } from 'events';
+/** JSON model data from the sync engine — may arrive as a pre-parsed object or a JSON string. */
+type SyncDeltaPayload = Record<string, unknown> | string | null;
+export interface SyncDelta {
+    id: number;
+    /**
+     * Delta action type — full Linear-compatible vocabulary.
+     *
+     * Core CRUD:
+     *   I — Insert
+     *   U — Update
+     *   D — Delete (hard)
+     *   A — Archive (soft delete)
+     *   V — Unarchive (reVive)
+     *
+     * Permission / access control:
+     *   C — Covering: client gained permission to see an existing entity
+     *       (treated as insert by the client — see handleCovering path).
+     *   G — GroupAdded: recipient was added to a sync group. Paired with
+     *       subsequent 'C' deltas for each newly-visible entity.
+     *   S — GroupRemoved: recipient lost access to a sync group. Client
+     *       purges affected entities from its local store.
+     */
+    actionType: 'I' | 'U' | 'D' | 'A' | 'V' | 'C' | 'G' | 'S';
+    modelName: string;
+    modelId: string;
+    data: SyncDeltaPayload;
+    previousData?: SyncDeltaPayload;
+    metadata?: SyncDeltaPayload;
+    syncGroups: string[];
+    createdBy?: string;
+    transactionId?: string;
+    clientMutationId?: string;
+    createdAt: string;
+}
+/**
+ * Payload for legacy actionType 'G' deltas emitted by EmitGroupChange.
+ * Carries both added and removed groups in one delta, forces full re-bootstrap.
+ */
+export interface SyncGroupChangePayload {
+    removedGroups: string[];
+    addedGroups: string[];
+}
+/**
+ * Payload for incremental actionType 'G' deltas emitted by EmitGroupAdded.
+ * Signals that the recipient has joined a single sync group; subsequent
+ * 'C' (Covering) deltas will deliver the newly-visible entities. No
+ * re-bootstrap required.
+ */
+export interface GroupAddedPayload {
+    group: string;
+    userId: string;
+}
+/**
+ * Payload for actionType 'S' deltas emitted by EmitGroupRemoved.
+ * Signals that the recipient has lost access to a sync group. The client
+ * purges affected local entities and updates its subscription metadata.
+ */
+export interface GroupRemovedPayload {
+    group: string;
+    userId: string;
+}
+export interface VersionVector {
+    tasks: number;
+    projects: number;
+    users: number;
+    events: number;
+    inboxitems: number;
+    teams: number;
+    assignments: number;
+    comments: number;
+    threads: number;
+    [entityType: string]: number;
+}
+export interface SyncCapabilities {
+    partialBootstrap?: boolean;
+    compressedDeltas?: boolean;
+    streamingBootstrap?: boolean;
+    batchedDeltas?: boolean;
+}
+export interface SyncWebSocketOptions {
+    /** Base HTTP URL of the sync server */
+    baseUrl?: string;
+    url?: string;
+    userId: string;
+    organizationId: string;
+    lastSyncId?: number;
+    syncGroups?: string[];
+    versions?: VersionVector;
+    capabilities?: SyncCapabilities;
+    reconnectDelay?: number;
+    maxReconnectDelay?: number;
+    /**
+     * Collaboration event type keys to listen for (e.g., ['sheet:selection', 'slide:cursor']).
+     * Wire messages with matching types (underscore format) will be emitted as events.
+     */
+    collaborationEvents?: string[];
+    /**
+     * Participant kind to declare on the WS upgrade. Defaults to `'user'`
+     * (session-auth, web app). Agent runtimes (Node workers) pass
+     * `'agent'` so the server's `agentTokenProvider`
+     * routes them through capability-token verification instead of
+     * session auth. The server reads this as the `kind` query param.
+     */
+    kind?: 'user' | 'agent' | 'system';
+    /**
+     * Biscuit capability bearer token. When set, sent as
+     * `?authorization=Bearer+<token>` on the WS upgrade — query-param
+     * form so it works in both Node (no header support) and browsers.
+     * The server's auth path accepts either form. Required for
+     * `kind: 'agent'`; ignored for `kind: 'user'`.
+     */
+    capabilityToken?: string;
+}
+/**
+ * Bootstrap hint from server indicating full or partial bootstrap is needed.
+ * Properties are optional since server payload structure may vary.
+ */
+export interface BootstrapHint {
+    tables?: string[];
+    reason?: 'too_far_behind' | 'too_many_deltas' | 'missing_entities';
+    staleTables?: string[];
+    totalDeltaCount?: number;
+}
+/** Bootstrap data event payload */
+export interface BootstrapDataEvent {
+    entityType: string;
+    data: unknown;
+    isComplete: boolean;
+    cursor?: string;
+}
+/**
+ * Presence update event payload — mirrors the wire frame's `payload`
+ * field (apps/sync-server/src/hub/types.ts PresenceUpdateMessage).
+ *
+ * Every consumer (web entity-presence cache, PresenceStream,
+ * agent-runtime presence reducer) reads its own subset; this type is
+ * the union of what the server actually sends. Stripping fields at
+ * this layer (the prior bug) silently broke rich-presence consumers
+ * that needed `kind`, `activity`, `isAgent` to dispatch correctly.
+ */
+export interface PresenceUpdateEvent {
+    /** Server-stamped transition: 'enter' on join + roster snapshot,
+     *  'update' on activity change, 'leave' on disconnect. */
+    kind?: 'enter' | 'update' | 'leave';
+    userId: string;
+    status: string;
+    syncGroups?: string[];
+    activity?: {
+        entityType: string;
+        entityId: string;
+        path?: string;
+        range?: {
+            startLine: number;
+            endLine: number;
+            startColumn?: number;
+            endColumn?: number;
+        };
+        field?: string;
+        meta?: Record<string, unknown>;
+        action: string;
+        detail?: string;
+    };
+    /** Server-derived from the connection's userId prefix. Clients must
+     *  not self-declare — server is the source of truth. */
+    isAgent?: boolean;
+    timestamp?: number;
+    /** Server stamps every presence frame with this participant's open
+     *  intent claims so peers see them without a separate channel. Wire
+     *  shape mirrors `apps/sync-server/src/hub/types.ts IntentClaim`. */
+    activeIntents?: Array<{
+        intentId: string;
+        entityType: string;
+        entityId: string;
+        path?: string;
+        range?: {
+            startLine: number;
+            endLine: number;
+            startColumn?: number;
+            endColumn?: number;
+        };
+        action: string;
+        field?: string;
+        meta?: Record<string, unknown>;
+        declaredAt: number;
+        expiresAt: number;
+    }>;
+    localTime?: string;
+    type?: string;
+    timezone?: string;
+    socketId?: string;
+}
+/**
+ * Core event map — transport-level events that every SyncWebSocket emits.
+ * SDK consumers extend this with app-specific collaboration events.
+ */
+export interface CoreSyncEventMap {
+    connected: [];
+    disconnected: [CloseEvent];
+    reconnecting: [{
+        attempt: number;
+        delay: number;
+    }];
+    delta: [SyncDelta];
+    delta_batch: [SyncDelta[]];
+    bootstrap_required: [BootstrapHint];
+    bootstrap_data: [BootstrapDataEvent];
+    presence_update: [PresenceUpdateEvent];
+    error: [Error];
+    session_error: [Error];
+    /**
+     * The WebSocket `onclose` fired before `onopen` — the handshake itself
+     * failed. The browser cannot expose the HTTP status (it shows as code
+     * 1006 with no reason), so the consumer should run an authenticated
+     * HTTP probe to distinguish auth failure (session expired) from a
+     * generic network issue.
+     */
+    handshake_failed: [CloseEvent];
+    reconnect_failed: [{
+        attempts: number;
+    }];
+    /**
+     * Server-initiated notification that a previously-active claim's
+     * TTL has expired. Consumers (e.g., the participant SDK) re-mint
+     * a fresh capability and re-claim, OR accept the drop. The claim
+     * is already inactive on the server side by the time this fires —
+     * no client-side action needed unless re-claiming.
+     */
+    claim_expired: [{
+        claimId: string;
+    }];
+    /**
+     * Server rejected an `intent_begin` because another participant
+     * already holds an open claim on the same target (cooperative
+     * mutex enforced server-side). Surfaces to the participant-level
+     * IntentStream so the caller knows their announce was denied.
+     * Payload mirrors the wire frame's `payload`.
+     */
+    intent_rejected: [Record<string, unknown>];
+}
+/**
+ * Collaboration event — app-specific real-time events (selection, cursors, etc.)
+ * Each event is a [payload] tuple matching the EventEmitter convention.
+ */
+export type DefaultCollaborationEvents = Record<string, never>;
+/**
+ * Constraint for event maps: every value must be a tuple of handler args.
+ *
+ * Why a mapped type and not `Record<string, unknown[]>`?
+ * `Record<string, ...>` requires an implicit string index signature, which
+ * TypeScript interfaces don't have. So a closed interface like Ablo's
+ * `AbloCollaborationEvents` would fail to satisfy `Record<string, unknown[]>`,
+ * even though every one of its values IS a tuple. This mapped form iterates
+ * over `keyof T` instead of demanding a string index, so it accepts both
+ * closed interfaces and open Record types — while still enforcing
+ * "every value is an array."
+ */
+export type EventMap<T> = {
+    [K in keyof T]: unknown[];
+};
+/**
+ * Full event map = core + collaboration events.
+ * Pass your own TCollaboration to add app-specific events.
+ */
+export type SyncWebSocketEventMap<TCollaboration extends EventMap<TCollaboration> = DefaultCollaborationEvents> = CoreSyncEventMap & TCollaboration;
+export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboration> = DefaultCollaborationEvents> extends EventEmitter {
+    /**
+     * Subscribe to events with automatic cleanup.
+     * Returns unsubscribe function for clean disposal.
+     */
+    subscribe<K extends keyof SyncWebSocketEventMap<TCollaboration>>(event: K, handler: (...args: SyncWebSocketEventMap<TCollaboration>[K]) => void): () => void;
+    /**
+     * Send a collaboration event (app-specific real-time message).
+     * The wire format is `{ type: messageType, payload: { ...payload, timestamp } }`.
+     */
+    sendCollaborationEvent<K extends string & keyof TCollaboration>(messageType: K, payload: TCollaboration[K] extends [infer P] ? Omit<P & Record<string, unknown>, 'timestamp'> : never): void;
+    private ws;
+    private options;
+    private reconnectAttempts;
+    /** Stop retrying after this many consecutive failures (backoff caps at 30s, so ~7.5 min total) */
+    private static readonly MAX_RECONNECT_ATTEMPTS;
+    private reconnectTimer;
+    /** Periodic catchup interval — polls for missed deltas every 30s while connected */
+    private catchupInterval;
+    /**
+     * Application-level heartbeat. The browser WebSocket API hides RFC 6455
+     * protocol-level ping/pong from JavaScript, so the server's `ws.ping()`
+     * keepalive can't be observed by client code — meaning the client cannot
+     * tell a healthy idle connection apart from a "zombie" socket where TCP
+     * silently broke (laptop sleep, NAT timeout, mobile handoff). We send an
+     * application-level `{ type: 'ping' }` every 30s and force-close the
+     * socket if no inbound traffic arrives within 10s. ANY inbound message
+     * counts as proof-of-life — the explicit `pong` is just a guarantee that
+     * something will arrive even on an idle stream.
+     */
+    private heartbeatTimer;
+    private heartbeatTimeoutTimer;
+    private static readonly HEARTBEAT_INTERVAL_MS;
+    private static readonly HEARTBEAT_TIMEOUT_MS;
+    private isConnecting;
+    private isManualClose;
+    /** When true, a session error has been detected (from any path — WS close or HTTP bootstrap).
+     *  Suppresses reconnection and Sentry error capture to avoid cascading noise. */
+    private _sessionErrorDetected;
+    /** True once `onopen` has fired at least once on the current socket. Reset each
+     *  time a new socket is created in `connect()`. Used by `onclose` to detect
+     *  handshake failures (close before open) — the one signal we have for "the
+     *  server rejected the upgrade" since browsers hide the HTTP status (e.g.
+     *  401) behind the opaque 1006 close code. */
+    private _everOpened;
+    /**
+     * Diagnostic snapshot of the last connection lifecycle. Persisted across
+     * the lifetime of the SyncWebSocket so that any subsequent "not connected"
+     * rejection can quote the actual root cause (close code + reason + when)
+     * instead of bottoming out at a generic error string. Browser WS code 1006
+     * hides the real reason, so we layer on our own signals: `forceCloseReason`
+     * captures heartbeat trips / send failures, `everOpened` distinguishes
+     * handshake reject from mid-session drop, and `sessionErrorAt` tells us
+     * whether reconnect is suppressed.
+     */
+    private lastOpenAt;
+    private lastCloseAt;
+    private lastCloseCode;
+    private lastCloseReason;
+    private lastForceCloseReason;
+    private sessionErrorAt;
+    private lastSyncId;
+    private versionVector;
+    private syncCursor;
+    /** Registered collaboration event keys (colon format) for dispatch in onmessage */
+    private collaborationEventTypes;
+    /**
+     * In-flight `commit` mutation requests keyed by clientTxId. Resolved when
+     * a matching `mutation_result` frame arrives from the server, or rejected on
+     * timeout / disconnect. Lets consumers await a server ack for mutations
+     * sent over the same socket that streams deltas.
+     */
+    private pendingMutations;
+    /**
+     * In-flight `claim` requests keyed by claimId. Resolved when the
+     * matching `claim_ack` arrives, or rejected on timeout/disconnect.
+     * Same shape as pendingMutations — Phoenix-style request/response
+     * over a multiplexed connection.
+     */
+    private pendingClaims;
+    constructor(options: SyncWebSocketOptions);
+    /**
+     * Mark that a session error has been detected (e.g. 401 from HTTP bootstrap).
+     * Suppresses further reconnection attempts and Sentry error capture.
+     */
+    setSessionErrorDetected(): void;
+    /**
+     * Connect to the sync engine WebSocket
+     */
+    connect(): void;
+    /**
+     * Setup WebSocket event handlers
+     */
+    private setupEventHandlers;
+    /**
+     * Handle incoming sync delta
+     */
+    private handleDelta;
+    /**
+     * Send acknowledgment for received delta with version vector.
+     *
+     * This is the SOLE forward-mover of `this.lastSyncId` for live
+     * deltas. Called by `BaseSyncedStore.flushPendingDeltas` with the
+     * `persistedSyncId` watermark — i.e. only after the deltas have
+     * actually committed to IDB. Keeping the cursor advance here (rather
+     * than at receipt in `handleDelta`/`handleSyncResponse`) means the
+     * cursor never gets ahead of the persisted view, so reconnect/
+     * catch-up requests can't accidentally skip un-persisted deltas.
+     */
+    private sendAck;
+    /**
+     * Public wrapper for sending ack from outside the class
+     */
+    acknowledge(syncId: number): void;
+    /**
+     * Send message to server
+     */
+    send(message: any): void;
+    /**
+     * Send a `commit` mutation request over the existing WebSocket and
+     * resolve when the server's `mutation_result` frame comes back with
+     * the same `clientTxId`. The wire-level frame is `{ type: 'commit',
+     * payload: { operations, clientTxId } }` — matching the
+     * `handleCommit` path on `apps/sync-server/src/hub/Hub.ts` (see the
+     * dispatch at Hub.ts:737).
+     *
+     * Historical naming note: this was originally `sendBatchAck` back when
+     * the Go sync-engine used a GraphQL `batchAck` mutation. The TS
+     * sync-server uses `type: 'commit'` over WebSocket exclusively. The
+     * method name now matches the wire protocol so the ack/commit naming
+     * confusion stops here.
+     *
+     * Times out after 15s of silence from the server. The socket may close
+     * during an in-flight mutation (network flap, server restart); we do
+     * NOT auto-retry here — the caller's TransactionQueue owns retry +
+     * offline replay semantics and the SDK shouldn't duplicate that logic.
+     */
+    sendCommit(operations: ReadonlyArray<{
+        type: string;
+        model: string;
+        id: string;
+        input?: Record<string, unknown>;
+        /**
+         * Per-op client transaction id. The server stamps this onto
+         * `sync_deltas.transaction_id` so the originating client
+         * recognizes the broadcast as an echo of its own optimistic
+         * mutation (echo detection in `SyncClient.applyDeltaBatchToPool`).
+         * Distinct from the batch-level `clientTxId` argument below
+         * (which keys `mutation_log` for retry idempotency). See
+         * `apps/sync-server/docs/OPTIMISTIC_RECONCILIATION.md`.
+         */
+        transactionId?: string;
+        readAt?: number | null;
+        onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+    }>, clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null): Promise<{
+        lastSyncId: number;
+    }>;
+    /**
+     * Send a commit frame without waiting for `mutation_result`.
+     *
+     * This backs the public `wait: 'queued'` API: the socket accepted the
+     * frame for delivery, but the server has not confirmed it yet. The
+     * eventual `mutation_result` frame is intentionally ignored by this
+     * instance because no pending resolver is registered.
+     */
+    sendCommitQueued(operations: ReadonlyArray<{
+        type: string;
+        model: string;
+        id: string;
+        input?: Record<string, unknown>;
+        transactionId?: string;
+        readAt?: number | null;
+        onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+    }>, clientTxId: string, causedByTaskId?: string | null): void;
+    /**
+     * Activate a participant claim on this connection. Multiplexed
+     * subscription pattern (Phoenix Channels / Pusher) — the same
+     * connection can hold N concurrent claims, each scoped to a
+     * different set of sync groups.
+     *
+     * Returns a promise that resolves with the server-canonicalized
+     * `syncGroups` and effective `ttlSeconds` once `claim_ack` arrives,
+     * or rejects with a typed error on `success: false` ack /
+     * timeout / disconnect.
+     *
+     * Why this exists: the old scoped-participant path opened a separate
+     * WS per scope. With claims, the SDK reuses the existing session/agent
+     * connection — one TCP, N logical participants. See
+     * `apps/sync-server/docs/PARTICIPANT_CLAIMS.md` for the migration
+     * framing (Phase A.1).
+     */
+    sendClaim(claimId: string, syncGroups: ReadonlyArray<string>, options?: {
+        capabilityToken?: string;
+        ttlSeconds?: number;
+        timeoutMs?: number;
+    }): Promise<{
+        syncGroups: string[];
+        ttlSeconds?: number;
+    }>;
+    /**
+     * Drop a previously-active claim. Idempotent — `release` is
+     * fire-and-forget per the wire contract; the server accepts
+     * unknown claimIds silently so disconnect-time release storms
+     * never error. No ack is expected.
+     *
+     * If a claim's send promise is still pending (no claim_ack yet),
+     * we reject it locally — the user explicitly chose to release.
+     */
+    sendRelease(claimId: string): void;
+    /**
+     * Replace the capability token used for authentication. The new
+     * value is read by the next URL-build (i.e., next connect / reconnect
+     * cycle). The currently-open WS is NOT torn down — servers keep
+     * connections alive past cap expiry until they decide to close, and
+     * a forced reconnect would interrupt in-flight deltas. The cap-mint
+     * scheduler in `Ablo.ts` calls this on each successful refresh so
+     * reconnects after server-initiated close pick up the fresh token.
+     */
+    setCapabilityToken(token: string): void;
+    /**
+     * Send spreadsheet selection presence
+     */
+    sendSheetSelection(sheetId: string, selectedCells: Array<{
+        ref: string;
+    }>): void;
+    /**
+     * Send slide layer selection presence
+     */
+    sendSlideSelection(deckId: string, slideId: string, selectedLayers: Array<{
+        layerId: string;
+    }>): void;
+    /**
+     * Send slide cursor position for real-time collaboration
+     * Note: Throttling should be handled by the caller (e.g., useSlideCursorBroadcast hook)
+     */
+    sendSlideCursor(deckId: string, slideId: string, x: number, y: number): void;
+    /**
+     * Send presence update to server.
+     * Use this for:
+     * - Updating timezone (improves localTime accuracy shown to other users)
+     * - Manual status changes (away, custom status)
+     *
+     * Note: "online" status is automatically set by server on WebSocket connect,
+     * and "offline" is set on disconnect. You don't need to call this for basic online/offline.
+     *
+     * @param status - "online", "away", or custom status string
+     * @param customStatus - Optional custom status message
+     */
+    sendPresenceUpdate(status?: 'online' | 'away' | 'offline', customStatus?: string): void;
+    /**
+     * Schedule reconnection with exponential backoff
+     */
+    private scheduleReconnect;
+    /**
+     * Reset reconnect attempt counter. Called when network comes back online
+     * to allow a fresh reconnect cycle after the max was previously reached.
+     */
+    resetReconnectAttempts(): void;
+    /**
+     * Stop the periodic catchup interval
+     */
+    private stopCatchupInterval;
+    /**
+     * Disconnect from WebSocket
+     */
+    disconnect(): void;
+    /**
+     * Application-level heartbeat. Every `HEARTBEAT_INTERVAL_MS` while
+     * `OPEN`, send `{ type: 'ping' }` and arm a `HEARTBEAT_TIMEOUT_MS`
+     * watchdog. Any inbound frame (handled in `onmessage`) clears the
+     * watchdog. If the watchdog fires, we treat the connection as
+     * zombie and force-close it — `onclose` then triggers the existing
+     * reconnect path.
+     *
+     * Why both sides need this:
+     *  - The server sends RFC 6455 protocol pings via `ws.ping()` every
+     *    30s. Browsers auto-respond with a pong but DO NOT expose either
+     *    frame to JavaScript, so the client is blind to its own keepalive.
+     *  - On a half-open TCP (laptop wake, NAT timeout, mobile handoff)
+     *    the browser may keep `readyState === OPEN` for minutes before
+     *    the OS surfaces the broken connection. App-level traffic is
+     *    the only signal we can observe.
+     */
+    private startHeartbeat;
+    private stopHeartbeat;
+    private clearHeartbeatTimeout;
+    /**
+     * Force-close the socket from the client side using a private 4xxx
+     * code. Callers expect `onclose` to fire; that handler runs the
+     * existing reconnect / handshake-failed dispatch. Wrapped in
+     * try/catch because `close()` on a CLOSING/CLOSED socket throws on
+     * some browsers.
+     */
+    private forceClose;
+    /**
+     * Get connection state
+     */
+    isConnected(): boolean;
+    /**
+     * Snapshot of recent connection lifecycle state, for diagnostic logs
+     * and error messages. Cheap to call (no I/O); safe to log every time
+     * a send is rejected so we can attribute "not connected" rejections
+     * to the actual root cause (handshake reject vs heartbeat zombie vs
+     * session expiry vs explicit close).
+     */
+    getConnectionDiagnostics(): {
+        readyState: number | null;
+        isConnecting: boolean;
+        isManualClose: boolean;
+        sessionErrorDetected: boolean;
+        everOpened: boolean;
+        reconnectAttempts: number;
+        maxReconnectAttempts: number;
+        lastOpenAt: number | null;
+        lastCloseAt: number | null;
+        lastCloseCode: number | null;
+        lastCloseReason: string | null;
+        lastForceCloseReason: string | null;
+        sessionErrorAt: number | null;
+        msSinceLastOpen: number | null;
+        msSinceLastClose: number | null;
+    };
+    /**
+     * Build a richly-diagnosed "not connected" error so callers (and the
+     * logs they emit) can attribute the rejection. The message embeds the
+     * dominant signal in human-readable form; the structured detail is
+     * also attached as `error.diagnostics` for log scrapers.
+     */
+    private notConnectedError;
+    /** Returns the sync groups this connection is subscribed to. */
+    getSyncGroups(): string[];
+    /**
+     * Update last sync ID (for persistence)
+     */
+    setLastSyncId(syncId: number): void;
+    /**
+     * Get current version vector
+     */
+    getVersionVector(): VersionVector;
+    /**
+     * Update version vector for specific entity type
+     */
+    updateVersionVector(entityType: string, version: number): void;
+    /**
+     * Set version vector (for initialization)
+     */
+    setVersionVector(versions: VersionVector): void;
+    /**
+     * Update sync cursor (for incremental sync)
+     */
+    setSyncCursor(cursor: string | null): void;
+    /**
+     * Get current sync cursor
+     */
+    getSyncCursor(): string | null;
+    /**
+     * Get the highest syncId seen this session (for persistence on clean shutdown)
+     */
+    getLastSyncId(): number;
+    /**
+     * Linear-style incremental sync request
+     */
+    requestIncrementalSync(): Promise<void>;
+    /**
+     * Request bootstrap for specific entities
+     */
+    requestBootstrap(entities?: string[]): Promise<void>;
+    /**
+     * Handle sync response from server
+     */
+    private handleSyncResponse;
+    /**
+     * Handle bootstrap response from server
+     */
+    private handleBootstrapResponse;
+    /**
+     * Handle presence update from server. The wire frame's payload is
+     * forwarded as-is so every consumer (web entity cache,
+     * PresenceStream, agent runtime) reads from the same shape.
+     * Stripping fields here was a prior bug — it silently dropped
+     * `kind`, `activity`, `syncGroups`, `isAgent` for rich consumers.
+     *
+     * Wire frame (apps/sync-server/src/hub/types.ts PresenceUpdateMessage):
+     *   { type: 'presence_update', payload: { kind, userId, status,
+     *     syncGroups, activity, isAgent, timestamp, activeIntents } }
+     */
+    private handlePresenceUpdate;
+}
+export {};