@abloatai/ablo 0.8.0 → 0.9.0

package/dist/sync/NetworkProbe.js

@@ -6,12 +6,15 @@
  * After laptop sleep/wake, it may report true before WiFi/DNS are functional.
  *
  * This module provides an authenticated probe against the sync server to verify
- * real connectivity + session validity in a single round-trip. The probe hits
- * `/api/auth/check`, which runs the SAME auth middleware as the WebSocket
- * upgrade path:
- *   204 No Content → reachable, session cookie valid
- *   401/403        → reachable, session expired or invalid
- *   network fail   → unreachable
+ * real connectivity + credential validity in a single round-trip. The probe
+ * hits `/api/auth/check`, which runs the SAME auth middleware as the WebSocket
+ * upgrade path, and classifies the response into a single {@link ProbeOutcome}
+ * via the closed recovery taxonomy ({@link classifyRecovery}):
+ *   204 No Content                         → `reachable`        (credential valid)
+ *   401 `apikey_expired` (ephemeral key)   → `credential_stale` (re-mint & retry, NO sign-out)
+ *   401 `session_expired` / bare 401       → `session_expired`  (sign out)
+ *   401/403 credential-type/config/perm    → `auth_blocked`     (stop, no loop, no sign-out)
+ *   network fail / offline                 → `unreachable`
  *
  * This closes a real gap: the browser's WebSocket API hides HTTP status from
  * the handshake, so a 401 on the WS upgrade surfaces only as `close code
@@ -21,8 +24,39 @@
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine
  */
+import { z } from 'zod';
 import { getContext } from '../context.js';
-import { SyncSessionError, isRetryableCode } from '../errors.js';
+import { classifyRecovery } from '../errors.js';
+import { withAuthHeaders } from '../auth/credentialSource.js';
+/**
+ * The closed set of probe outcomes — one value carrying both reachability and
+ * credential disposition, so the {@link ConnectionManager} branches on a single
+ * exhaustive discriminant instead of reconstructing intent from a trio of
+ * booleans. Mirrors the {@link RecoveryClass} taxonomy at the connectivity tier.
+ */
+export const PROBE_OUTCOMES = [
+    /** Server reachable and the access credential is currently valid. */
+    'reachable',
+    /** Could not reach the server (offline / DNS / TLS / timeout). */
+    'unreachable',
+    /** Reachable, but the long-lived login is gone → terminal, sign out. */
+    'session_expired',
+    /** Reachable, but the ephemeral access key (`ek_`/`rk_`) expired → silently
+     *  re-mint a fresh key from the still-valid login and retry. NOT a sign-out. */
+    'credential_stale',
+    /** Reachable, but the credential TYPE/config was rejected (wrong key kind,
+     *  untrusted issuer, no org, a 403) → stop; neither reconnecting nor re-auth
+     *  helps. Distinct from a sign-out. */
+    'auth_blocked',
+];
+/** Zod enum derived from {@link PROBE_OUTCOMES}. */
+export const probeOutcomeSchema = z.enum(PROBE_OUTCOMES);
+/** Result of a network probe: a single {@link ProbeOutcome} plus round-trip
+ *  latency (null when the probe never completed). */
+export const probeResultSchema = z.object({
+    outcome: probeOutcomeSchema,
+    latencyMs: z.number().nullable(),
+});
 const PROBE_TIMEOUT_MS = 4000;
 /**
  * Derive the probe URL from a sync-server base URL. Accepts `ws://`,
@@ -46,11 +80,14 @@ function resolveProbeUrl(baseUrl) {
  * Returns reachability AND session status in a single call, so the
  * ConnectionStore can make the right state transition without guessing.
  *
- * @param baseUrl The sync-server base URL (HTTP or WS scheme accepted).
- *                If omitted, falls back to `NEXT_PUBLIC_GO_SERVER_URL` →
- *                `http://localhost:8080` for backwards compatibility.
+ * @param input The sync-server base URL (HTTP or WS scheme accepted), or an
+ *              options bag with `authToken`. A bare string is still accepted
+ *              for backwards compatibility.
  */
-export async function probeNetwork(baseUrl) {
+export async function probeNetwork(input) {
+    const baseUrl = typeof input === 'string' ? input : input?.baseUrl;
+    const getAuthToken = typeof input === 'string' ? undefined : input?.getAuthToken;
+    const authToken = typeof input === 'string' ? undefined : input?.authToken;
     const url = resolveProbeUrl(baseUrl);
     // Fast-fail: if navigator.onLine is false, skip the probe entirely.
     // This is the ONE case where navigator.onLine is reliable (MDN: "false
@@ -58,51 +95,90 @@ export async function probeNetwork(baseUrl) {
     // because Node 22+ exposes `navigator` with `onLine === undefined`,
     // and `!undefined === true` would short-circuit the probe server-side.
     if (typeof navigator !== 'undefined' && navigator.onLine === false) {
-        return { reachable: false, sessionValid: null, latencyMs: null };
+        return { outcome: 'unreachable', latencyMs: null };
     }
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
     const start = performance.now();
     try {
+        const headers = withAuthHeaders(getAuthToken, { 'Cache-Control': 'no-cache' }, authToken);
         const response = await fetch(url, {
             method: 'HEAD',
-            credentials: 'include', // Send cookies for session check
             signal: controller.signal,
             // Cache-bust to avoid stale responses
-            headers: { 'Cache-Control': 'no-cache' },
+            headers,
         });
         const latencyMs = Math.round(performance.now() - start);
         // The probe is a HEAD (no body), but the sync-server sets `X-Auth-Failure:
-        // <code>` on every auth rejection — feed that to the code-aware detector so
-        // only a genuine session/JWT EXPIRY marks the session invalid. A non-expiry
-        // auth failure (e.g. api_key_required, jwt_issuer_untrusted) leaves
-        // sessionValid alone — the user IS logged in; signing them out wouldn't fix
-        // a credential-type/config problem and just bounces them to /signin.
+        // <code>` on every auth rejection. Route the code through the closed
+        // recovery taxonomy so each failure mode gets its correct outcome — the
+        // whole reason this taxonomy exists: an expired ephemeral key
+        // (`access_credential_expiry`) must re-mint, NOT sign the user out the way
+        // a genuine login expiry (`session_expiry`) does, and NOT wedge the way a
+        // credential-type/config rejection (`auth_blocked`) does.
         const authFailure = response.headers.get('x-auth-failure');
-        const failureBody = authFailure
-            ? JSON.stringify({ code: authFailure })
-            : undefined;
-        if (SyncSessionError.isSessionErrorResponse(response.status, failureBody)) {
-            // Server reachable but session expired/invalid
-            getContext().logger.info('[NetworkProbe] Server reachable, session expired', {
-                status: response.status,
-                latencyMs,
-            });
-            return { reachable: true, sessionValid: false, latencyMs };
+        if (authFailure) {
+            const recovery = classifyRecovery(authFailure);
+            switch (recovery) {
+                case 'session_expiry':
+                    getContext().logger.info('[NetworkProbe] Server reachable, login expired', {
+                        status: response.status,
+                        code: authFailure,
+                        latencyMs,
+                    });
+                    return { outcome: 'session_expired', latencyMs };
+                case 'access_credential_expiry':
+                    getContext().logger.info('[NetworkProbe] Server reachable, access key stale — will re-mint', {
+                        status: response.status,
+                        code: authFailure,
+                        latencyMs,
+                    });
+                    return { outcome: 'credential_stale', latencyMs };
+                case 'auth_blocked':
+                case 'permission':
+                case 'none':
+                    // A non-expiry auth rejection — wrong credential type/config, a 403,
+                    // or an auth-tagged code this SDK doesn't recognise. Re-auth re-mints
+                    // the same rejected credential and retrying won't help, so STOP
+                    // rather than reconnect-loop or sign the user out.
+                    getContext().logger.warn('[NetworkProbe] Reachable but auth-blocked (non-retryable, non-expiry)', {
+                        status: response.status,
+                        code: authFailure,
+                        recovery,
+                        latencyMs,
+                    });
+                    return { outcome: 'auth_blocked', latencyMs };
+                case 'transient':
+                    // Retryable auth-tagged response — connectivity is proven; fall
+                    // through to `reachable` and let the normal retry path handle it.
+                    break;
+                default: {
+                    const _exhaustive = recovery;
+                    void _exhaustive;
+                }
+            }
         }
-        // Reachable, but a NON-retryable auth/config failure that is NOT a session
-        // expiry (api_key_required, jwt_issuer_untrusted, …). Re-auth won't fix it
-        // and retrying won't either — signal authBlocked so the manager STOPS
-        // rather than reconnect-looping or signing the user out.
-        if (authFailure && !isRetryableCode(authFailure)) {
-            getContext().logger.warn('[NetworkProbe] Reachable but auth-blocked (non-retryable, non-expiry)', {
-                status: response.status,
-                code: authFailure,
+        else if (response.status === 401) {
+            // Bare 401 with no READABLE structured code. This is AMBIGUOUS and must
+            // NOT sign the user out on its own — two common causes are both
+            // recoverable, and only one is a real logout:
+            //   1. The server DID send `X-Auth-Failure: apikey_expired`, but it's a
+            //      custom header on a cross-origin response and the server didn't list
+            //      it in `Access-Control-Expose-Headers`, so the browser stripped it to
+            //      null (the network-change logout bug). The access key just needs a
+            //      re-mint.
+            //   2. A genuinely expired access key on a non-Ablo proxy / cookie path.
+            // So route to `credential_stale`: the FSM attempts a re-mint, and the ONLY
+            // way to actually sign out is the re-mint resolving `null` (login truly
+            // gone). If no refresher is wired, the bounded attempt counter falls
+            // through to `auth_blocked` (stop) — still never a spurious logout. This
+            // upholds the invariant: null is the only terminal path, never a bare 401.
+            getContext().logger.info('[NetworkProbe] Server reachable, bare 401 — re-mint (not sign-out)', {
                 latencyMs,
             });
-            return { reachable: true, sessionValid: true, authBlocked: true, latencyMs };
+            return { outcome: 'credential_stale', latencyMs };
         }
-        // 2xx (including 204) means reachable + session valid.
+        // 2xx (including 204) means reachable + credential valid.
         // 3xx/4xx (non-auth) still prove connectivity even though the probe
         // expected 204; log a warning so misconfigurations surface instead of
         // silently passing.
@@ -114,12 +190,12 @@ export async function probeNetwork(baseUrl) {
             });
         }
         else {
-            getContext().logger.debug('[NetworkProbe] Server reachable, session valid', {
+            getContext().logger.debug('[NetworkProbe] Server reachable, credential valid', {
                 status: response.status,
                 latencyMs,
             });
         }
-        return { reachable: true, sessionValid: true, latencyMs };
+        return { outcome: 'reachable', latencyMs };
     }
     catch (error) {
         clearTimeout(timeout);
@@ -127,7 +203,7 @@ export async function probeNetwork(baseUrl) {
         getContext().logger.info('[NetworkProbe] Probe failed', {
             reason: isAbort ? 'timeout' : error.message,
         });
-        return { reachable: false, sessionValid: null, latencyMs: null };
+        return { outcome: 'unreachable', latencyMs: null };
     }
     finally {
         clearTimeout(timeout);

package/dist/sync/SyncWebSocket.d.ts

@@ -8,40 +8,18 @@
  * - 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;
-}
+import type { MutationOperation } from '../interfaces/index.js';
+import type { ClientSyncDelta } from '../schema/sync-delta-wire.js';
+import { type AuthTokenGetter } from '../auth/credentialSource.js';
+/**
+ * The wire delta the client receives. Derived from the canonical
+ * `clientSyncDeltaSchema` (`@abloatai/ablo/schema`) via `z.infer` so the
+ * SDK and the sync-server share ONE contract instead of two hand-maintained
+ * interfaces. The action vocabulary (`I`/`U`/`D`/`A`/`V`/`C`/`G`/`S`) and the
+ * client-only extras (`metadata`, `clientMutationId`, deprecated flat
+ * `createdBy`) live in that schema; see its doc for the full field reference.
+ */
+export type SyncDelta = ClientSyncDelta;
 /**
  * Payload for legacy actionType 'G' deltas emitted by EmitGroupChange.
  * Carries both added and removed groups in one delta, forces full re-bootstrap.
@@ -121,6 +99,15 @@ export interface SyncWebSocketOptions {
      * the Biscuit→opaque-key migration.)
      */
     capabilityToken?: string;
+    /**
+     * Shared credential getter. When provided, WebSocket URL auth reads this
+     * instead of a copied `capabilityToken`, so reconnects use refreshed tokens
+     * from the SDK's single auth source.
+     */
+    /** Shared SDK auth getter. Preferred internal name. */
+    getAuthToken?: AuthTokenGetter;
+    /** @deprecated Use `getAuthToken`. Kept for direct low-level callers. */
+    getCapabilityToken?: AuthTokenGetter;
 }
 /**
  * Bootstrap hint from server indicating full or partial bootstrap is needed.
@@ -271,7 +258,7 @@ export interface CoreSyncEventMap {
     /**
      * Per-entity wait-queue snapshot: `{ target, queue: Intent[] }` with each
      * entry `status: 'queued'` + `position`. Broadcast to entity peers on every
-     * queue mutation — powers the reactive `ablo.<model>.claim.queue(id)` read.
+     * queue mutation — powers the reactive `ablo.<model>.claim.queue({ id })` read.
      */
     intent_queue: [Record<string, unknown>];
     intent_acquired: [Record<string, unknown>];
@@ -422,6 +409,16 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * Send message to server
      */
     send(message: any): void;
+    /**
+     * Project the SDK's `MutationOperation[]` onto the canonical wire
+     * `CommitMessage`. This is the single serialize boundary between the SDK op
+     * type (loose `type: string`, plus an SDK-internal `options` the server never
+     * reads) and the strict wire contract. The per-field map gives compile-time
+     * drift detection (a `CommitOperation` shape change breaks here) and the lone
+     * `as` narrows the validated op `type` to the wire union — the only
+     * loosening, localized to this boundary.
+     */
+    private buildCommitFrame;
     /**
      * Send a `commit` mutation request over the existing WebSocket and
      * resolve when the server's `mutation_result` frame comes back with
@@ -441,24 +438,7 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * 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<{
+    sendCommit(operations: ReadonlyArray<MutationOperation>, clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null): Promise<{
         lastSyncId: number;
     }>;
     /**
@@ -469,15 +449,7 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * 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;
+    sendCommitQueued(operations: ReadonlyArray<MutationOperation>, clientTxId: string, causedByTaskId?: string | null): void;
     /**
      * Activate a participant claim on this connection. Multiplexed
      * subscription pattern (Phoenix Channels / Pusher) — the same
@@ -514,15 +486,19 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      */
     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.
+     * Compatibility setter for direct SyncWebSocket users. The SDK-owned
+     * `Ablo()` path passes `getAuthToken`, so reconnect URL auth reads the
+     * shared credential source instead of this copied value.
      */
     setCapabilityToken(token: string): void;
+    getAuthToken(): string | undefined;
+    /**
+     * Return the credential that will be used by the next WebSocket upgrade.
+     * ConnectionManager reads this for HTTP auth probes so visibility/network
+     * checks authenticate the same way reconnects do.
+     */
+    getCapabilityToken(): string | undefined;
+    private resolveAuthToken;
     /**
      * Send spreadsheet selection presence
      */
@@ -692,4 +668,3 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      */
     private handlePresenceUpdate;
 }
-export {};

package/dist/sync/SyncWebSocket.js

@@ -11,6 +11,7 @@ import { EventEmitter } from 'events';
 import { getContext } from '../context.js';
 import { flushOfflineQueueOnce } from './OfflineFlush.js';
 import { AbloConnectionError, AbloError, CapabilityError, SyncSessionError, errorFromWire, toAbloError, } from '../errors.js';
+import { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL, } from '../auth/credentialSource.js';
 // ---------------------------------------------------------------------------
 // Ablo-specific collaboration events moved to apps/web/src/lib/sync/collaboration-events.ts
 // Consumers pass their own event types as TCollaboration generic parameter.
@@ -170,16 +171,10 @@ export class SyncWebSocket extends EventEmitter {
         }
         this.isConnecting = true;
         this.isManualClose = false;
-        // Pattern: one credential, server-resolved identity. The WS URL
-        // carries the credential (cap-token bearer in `?authorization=`
-        // for the cap path; session cookie in headers for the cookie
-        // path). The server's AuthProvider chain (`apiKeyProvider →
-        // agentTokenProvider → betterAuthProvider`) resolves identity
-        // from the verified credential — userId/organizationId are
-        // NEVER read from URL params in production. See
-        // `apps/sync-server/src/auth/provider.ts:148` (betterAuthProvider
-        // calls `auth.api.getSession({headers})`) and `agentTokenProvider`
-        // for the cap-token path.
+        // Pattern: one credential, server-resolved identity. The bearer travels
+        // in a `Sec-WebSocket-Protocol` value (built below), NOT the URL. The
+        // server is bearer-only (`apiKeyProvider`) and resolves identity from the
+        // verified token — userId/organizationId are NEVER read from URL params.
         const params = new URLSearchParams({
             // Intentionally omit lastSyncId, versions, capabilities from URL; these are sent in sync_request
             // and ack messages to avoid stale baselines on reconnect.
@@ -191,22 +186,28 @@ export class SyncWebSocket extends EventEmitter {
         if (this.options.kind && this.options.kind !== 'user') {
             params.set('kind', this.options.kind);
         }
-        // Capability bearer (query-param form so it works in both Node's
-        // global WebSocket — which can't set headers — and browsers).
-        if (this.options.capabilityToken) {
-            params.set('authorization', `Bearer ${this.options.capabilityToken}`);
-        }
         // Add sync groups if provided
         this.options.syncGroups.forEach((group) => {
             params.append('syncGroups', group);
         });
         const wsUrl = `${this.options.url}?${params.toString()}`;
+        // Carry the bearer in a `Sec-WebSocket-Protocol` value, NOT the URL. A
+        // browser can't set an Authorization header on a WS, but it CAN offer
+        // subprotocols — and unlike the query string, those don't land in ALB
+        // access logs, proxies, or browser history. The server reads
+        // `ablo.bearer.<token>` and selects the real `ablo.sync.v1` protocol,
+        // never echoing the token-bearing value back. (Token is the raw ek_/rk_,
+        // which is subprotocol-token-safe — alphanumerics + `_`.)
+        const authToken = this.resolveAuthToken();
+        const protocols = authToken
+            ? [`${WS_BEARER_SUBPROTOCOL_PREFIX}${authToken}`, WS_SYNC_SUBPROTOCOL]
+            : [WS_SYNC_SUBPROTOCOL];
         try {
             // Reset the handshake flag before wiring the new socket. Each connect()
             // gets its own lifecycle — a prior successful open on a previous socket
             // must not mask a handshake failure on the new one.
             this._everOpened = false;
-            this.ws = new WebSocket(wsUrl);
+            this.ws = new WebSocket(wsUrl, protocols);
             this.setupEventHandlers();
         }
         catch (error) {
@@ -303,11 +304,10 @@ export class SyncWebSocket extends EventEmitter {
                         this.handlePresenceUpdate(message);
                         break;
                     case 'mutation_result': {
-                        // Ack for a prior `commit` we sent. Wire format (mirrors
-                        // apps/sync-server/src/hub/types.ts MutationResultMessage):
-                        //   { type: 'mutation_result',
-                        //     payload: { clientTxId, serverTxId, success,
-                        //                lastSyncId?, error? } }
+                        // Ack for a prior `commit` we sent. Canonical shape is
+                        // `MutationResultMessage` in `@abloatai/ablo/wire`. This stays a
+                        // DEFENSIVE parse (not a typed cast) because the payload is
+                        // untrusted wire data that may be malformed or from an older server.
                         const p = message.payload ?? message;
                         const { clientTxId, success, lastSyncId, error } = p ?? {};
                         const pending = typeof clientTxId === 'string'
@@ -720,6 +720,32 @@ export class SyncWebSocket extends EventEmitter {
             }
         }
     }
+    /**
+     * Project the SDK's `MutationOperation[]` onto the canonical wire
+     * `CommitMessage`. This is the single serialize boundary between the SDK op
+     * type (loose `type: string`, plus an SDK-internal `options` the server never
+     * reads) and the strict wire contract. The per-field map gives compile-time
+     * drift detection (a `CommitOperation` shape change breaks here) and the lone
+     * `as` narrows the validated op `type` to the wire union — the only
+     * loosening, localized to this boundary.
+     */
+    buildCommitFrame(operations, clientTxId, causedByTaskId) {
+        const payload = {
+            operations: operations.map((op) => ({
+                type: op.type,
+                model: op.model,
+                id: op.id,
+                input: op.input,
+                transactionId: op.transactionId,
+                readAt: op.readAt,
+                onStale: op.onStale,
+            })),
+            clientTxId,
+        };
+        if (causedByTaskId)
+            payload.causedByTaskId = causedByTaskId;
+        return { type: 'commit', payload };
+    }
     /**
      * Send a `commit` mutation request over the existing WebSocket and
      * resolve when the server's `mutation_result` frame comes back with
@@ -754,10 +780,8 @@ export class SyncWebSocket extends EventEmitter {
                 // an open turn — keeps the wire shape stable for sessions
                 // that don't use turns. Servers that don't know the field
                 // ignore it; newer servers stamp it onto every delta.
-                const payload = { operations, clientTxId };
-                if (causedByTaskId)
-                    payload.causedByTaskId = causedByTaskId;
-                this.ws.send(JSON.stringify({ type: 'commit', payload }));
+                const frame = this.buildCommitFrame(operations, clientTxId, causedByTaskId);
+                this.ws.send(JSON.stringify(frame));
             }
             catch (error) {
                 clearTimeout(timeout);
@@ -778,10 +802,8 @@ export class SyncWebSocket extends EventEmitter {
         if (this.ws?.readyState !== WebSocket.OPEN) {
             throw this.notConnectedError('commit');
         }
-        const payload = { operations, clientTxId };
-        if (causedByTaskId)
-            payload.causedByTaskId = causedByTaskId;
-        this.ws.send(JSON.stringify({ type: 'commit', payload }));
+        const frame = this.buildCommitFrame(operations, clientTxId, causedByTaskId);
+        this.ws.send(JSON.stringify(frame));
     }
     /**
      * Activate a participant claim on this connection. Multiplexed
@@ -863,17 +885,29 @@ export class SyncWebSocket extends EventEmitter {
         }
     }
     /**
-     * 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.
+     * Compatibility setter for direct SyncWebSocket users. The SDK-owned
+     * `Ablo()` path passes `getAuthToken`, so reconnect URL auth reads the
+     * shared credential source instead of this copied value.
      */
     setCapabilityToken(token) {
         this.options.capabilityToken = token;
     }
+    getAuthToken() {
+        return this.resolveAuthToken();
+    }
+    /**
+     * Return the credential that will be used by the next WebSocket upgrade.
+     * ConnectionManager reads this for HTTP auth probes so visibility/network
+     * checks authenticate the same way reconnects do.
+     */
+    getCapabilityToken() {
+        return this.resolveAuthToken();
+    }
+    resolveAuthToken = () => {
+        return this.options.getAuthToken?.()
+            ?? this.options.getCapabilityToken?.()
+            ?? this.options.capabilityToken;
+    };
     /**
      * Send spreadsheet selection presence
      */

package/dist/sync/createIntentStream.js

@@ -93,6 +93,9 @@ export function createIntentStream(config, transport = null) {
                 // `settled()`. Absent status means active (wire back-compat).
                 if (claim.status && claim.status !== 'active')
                     continue;
+                const description = typeof claim.meta?.description === 'string'
+                    ? claim.meta.description
+                    : undefined;
                 activeByIntentId.set(claim.intentId, {
                     id: claim.intentId,
                     heldBy: event.userId,
@@ -106,6 +109,7 @@ export function createIntentStream(config, transport = null) {
                         meta: claim.meta,
                     },
                     reason: claim.action,
+                    ...(description ? { description } : {}),
                     ttlSeconds: Math.max(0, Math.floor((claim.expiresAt - Date.now()) / 1000)),
                     announcedAt: new Date(claim.declaredAt).toISOString(),
                     expiresAt: new Date(claim.expiresAt).toISOString(),
@@ -227,6 +231,11 @@ export function createIntentStream(config, transport = null) {
             },
         });
     }
+    function withDescription(meta, description) {
+        if (!description)
+            return meta;
+        return { ...(meta ?? {}), description };
+    }
     function mintHandle(args) {
         const intentId = crypto.randomUUID();
         const estimatedMs = args.ttl !== undefined ? toMs(args.ttl) : undefined;
@@ -273,7 +282,7 @@ export function createIntentStream(config, transport = null) {
                 path: resolved.path,
                 range: resolved.range,
                 field: resolved.field,
-                meta: resolved.meta,
+                meta: withDescription(resolved.meta, opts?.description),
                 action: opts?.reason ?? 'editing',
                 ttl: opts?.ttl,
                 queue: opts?.queue,

package/dist/types/streams.d.ts

@@ -340,6 +340,12 @@ export interface ClaimOptions extends IntentOptions {
      * app-specific phases.
      */
     readonly reason?: string;
+    /**
+     * Peer-visible explanation of the exact work being performed. This is more
+     * specific than `reason`: `reason` is the phase (`'renaming'`), while
+     * `description` is the instruction other agents should see.
+     */
+    readonly description?: string;
     /**
      * Join the server's fair FIFO queue on contention instead of being
      * rejected. The grant arrives asynchronously (`intent_acquired` if the
@@ -528,6 +534,7 @@ export interface ActiveIntent extends IntentDeclaration {
      * from "user editing X" without string-parsing `heldBy`.
      */
     readonly participantKind: 'human' | 'agent';
+    readonly description?: string;
     readonly announcedAt: string;
     readonly expiresAt: string;
 }
@@ -565,6 +572,8 @@ export interface Intent {
     readonly target: EntityRef;
     /** Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. */
     readonly action: string;
+    /** Peer-visible explanation of the work being performed. */
+    readonly description?: string;
     /** Participant holding it. */
     readonly heldBy: string;
     readonly participantKind: 'human' | 'agent';

package/dist/utils/mobx-setup.js

@@ -146,6 +146,7 @@ export function M1(target, propertyMetadata, referenceMetadata) {
         'markAsPersisted',
         'clearChanges',
         'updateFromData',
+        'applyChanges',
     ];
     for (const methodName of actionMethods) {
         if (typeof Reflect.get(target, methodName) === 'function') {