@abloatai/ablo 0.7.0 → 0.9.0

package/dist/BaseSyncedStore.js

@@ -12,7 +12,7 @@
  * pull generic methods into this base class.
  */
 import { makeObservable, observable, computed, runInAction } from 'mobx';
-import { AbloConnectionError, AbloValidationError } from './errors.js';
+import { AbloConnectionError, AbloValidationError, toAbloError } from './errors.js';
 import { ConnectionManager } from './sync/ConnectionManager.js';
 import { PropertyType } from './types/index.js';
 import { SyncWebSocket, } from './sync/SyncWebSocket.js';
@@ -124,6 +124,7 @@ export class BaseSyncedStore {
     database;
     objectPool;
     modelRegistry;
+    auth;
     /**
      * Schema the store was constructed with. Persisted so the `query`
      * accessor namespace can build typed per-model reader actions lazily
@@ -199,6 +200,7 @@ export class BaseSyncedStore {
         this.database = dependencies.database;
         this.objectPool = dependencies.objectPool;
         this.modelRegistry = dependencies.modelRegistry;
+        this.auth = dependencies.auth;
         this.schema = dependencies.schema;
         this._syncServerUrl = dependencies.url;
         // Set this store as the global Model store
@@ -351,6 +353,24 @@ export class BaseSyncedStore {
      * return null.
      */
     connectionManager = null;
+    /**
+     * Re-mint hook for the short-lived access credential (the Stripe-style
+     * `ek_`/`rk_`). Wired by the React provider from its `getToken`/`authEndpoint`
+     * — the engine owns WHEN to refresh (a stale-credential probe / an external
+     * nudge), the integrator owns HOW to mint. Mirrors the `getToken` contract:
+     * resolves a token string on success, `null` when the long-lived login is
+     * gone (terminal), and THROWS on a transient/offline failure. Used by
+     * {@link performCredentialRefresh}. Absent ⇒ no silent re-mint (e.g. a static
+     * `apiKey` deployment whose credential source refreshes out-of-band).
+     */
+    credentialRefresher = null;
+    /** Single-flight guard so a wake nudge + an in-flight request + a probe don't
+     *  all mint at once (the classic "token thrash → random logout" bug). */
+    inFlightCredentialRefresh = null;
+    /** Teardown for the proactive credential lifecycle (refresh timer + wake/
+     *  online/focus listeners) installed by {@link startCredentialLifecycle};
+     *  cleared on {@link disconnect}. Null when no resolver is wired. */
+    credentialLifecycleTeardown = null;
     /**
      * Listeners registered via `subscribeSessionError()`. Fired when the
      * WebSocket closes with a session-invalid code (1008/4001/4003) or a
@@ -447,14 +467,18 @@ export class BaseSyncedStore {
                 }
             }
         }
-        throw lastError || new Error('Bootstrap failed after all retry attempts');
+        throw lastError
+            ? toAbloError(lastError)
+            : new AbloConnectionError('Bootstrap failed after all retry attempts', {
+                code: 'bootstrap_fetch_timeout',
+            });
     }
     /** Create a timeout promise for bootstrap attempts */
     createBootstrapTimeout(attempt) {
         const timeoutMs = BOOTSTRAP_CONFIG.OVERALL_TIMEOUT_MS + (attempt - 1) * 3_000;
         return new Promise((_, reject) => {
             setTimeout(() => {
-                reject(new Error(`Bootstrap timed out after ${timeoutMs}ms (attempt ${attempt})`));
+                reject(new AbloConnectionError(`Bootstrap timed out after ${timeoutMs}ms (attempt ${attempt})`, { code: 'bootstrap_fetch_timeout' }));
             }, timeoutMs);
         });
     }
@@ -527,6 +551,147 @@ export class BaseSyncedStore {
             return 'network_error';
         }
     }
+    /**
+     * Register the access-credential re-mint hook. Called by the React provider
+     * with a thunk that mints a fresh `ek_`/`rk_` (typically its `getToken`).
+     * See {@link credentialRefresher}.
+     */
+    setCredentialRefresher(refresher) {
+        this.credentialRefresher = refresher;
+    }
+    /**
+     * Re-mint the short-lived access credential and push it into the credential
+     * source, reporting a tri-state outcome the {@link ConnectionManager} maps to
+     * its FSM. The contract mirrors `getToken` (and PowerSync's `fetchCredentials`
+     * / Liveblocks' `authEndpoint`, but made explicit instead of overloading
+     * return/throw):
+     *   - token string  → `'refreshed'`     (fresh key in place; re-probe & reconnect)
+     *   - `null`        → `'session_error'` (login itself is gone → terminal, sign out)
+     *   - throw         → `'network_error'` (couldn't reach the mint endpoint → transient)
+     *
+     * SINGLE-FLIGHT: concurrent callers (a wake nudge, an in-flight request, the
+     * probe) share one in-flight promise so we never double-mint — the canonical
+     * fix for the "every 401 mints a token → thrash → spurious logout" anti-pattern.
+     *
+     * No refresher wired ⇒ `'refreshed'` (a no-op re-probe): a static-`apiKey`
+     * deployment has no session to re-mint from; its credential source refreshes
+     * out-of-band, so we just re-probe with whatever it currently holds.
+     */
+    async performCredentialRefresh() {
+        const refresher = this.credentialRefresher;
+        if (!refresher)
+            return 'refreshed';
+        if (this.inFlightCredentialRefresh)
+            return this.inFlightCredentialRefresh;
+        const run = (async () => {
+            try {
+                const token = await refresher();
+                if (!token) {
+                    // null = the long-lived login is gone (mint endpoint answered 401/403).
+                    // Terminal — the FSM routes this to sign-out.
+                    return 'session_error';
+                }
+                this.auth?.setAuthToken(token);
+                return 'refreshed';
+            }
+            catch (error) {
+                // A throw = transient (offline / mint endpoint unreachable / 5xx). The
+                // login may be perfectly valid; never sign out for this — back off and
+                // retry. Mirrors the `getToken` throw-vs-null contract end-to-end.
+                getContext().logger.warn('[BaseSyncedStore] Access-credential re-mint failed (transient)', {
+                    error: error?.message,
+                });
+                return 'network_error';
+            }
+        })();
+        this.inFlightCredentialRefresh = run;
+        try {
+            return await run;
+        }
+        finally {
+            this.inFlightCredentialRefresh = null;
+        }
+    }
+    /**
+     * Nudge the connection FSM to re-probe with the current credential. Idempotent
+     * and safe in any state (ignored while `connected`). Call after pushing a
+     * freshly-minted token via `setAuthToken`, or on an OS-wake signal, so a
+     * connection parked in `offline` / `backoff` / `auth_blocked` picks the new
+     * credential up immediately instead of waiting for the 30s watchdog.
+     */
+    nudgeReconnect() {
+        this.connectionManager?.send({ type: 'CREDENTIAL_REFRESHED' });
+    }
+    /**
+     * Install the access-credential lifecycle the CLIENT owns (this used to live
+     * in the React provider — wrong layer). Two parts:
+     *   1. REACTIVE — register `getToken` as the re-mint hook the FSM calls when a
+     *      probe finds the key stale (`credential_stale`) or on a nudge.
+     *   2. PROACTIVE — keep the short-lived key fresh ahead of trouble: a refresh
+     *      timer inside the TTL, plus re-mint on OS wake / network-online / tab
+     *      focus. Browser-only triggers are env-gated, so Node/agent hosts get
+     *      only the timer (a no-op there — agents use a static `apiKey`, no
+     *      resolver, so this is never called for them).
+     *
+     * Config-driven and invisible, like Supabase's `autoRefreshToken` — consumers
+     * never call a refresh method. Idempotent (a second call replaces the first);
+     * torn down on {@link disconnect}.
+     */
+    startCredentialLifecycle(getToken) {
+        this.stopCredentialLifecycle();
+        this.setCredentialRefresher(getToken);
+        // A transient failure is swallowed: the engine keeps its current token and
+        // the next trigger — or the reactive `credential_stale` path — retries. We
+        // never tear down or sign out on a failed proactive roll.
+        const refresh = async () => {
+            try {
+                const token = await getToken();
+                if (token) {
+                    // Push into the shared credential source (read lazily by bootstrap
+                    // HTTP, probes, and the WS reconnect URL), then nudge a parked
+                    // connection to re-probe with the fresh key. Same two steps the
+                    // engine's `setAuthToken` wrapper performs.
+                    this.auth?.setAuthToken(token);
+                    this.nudgeReconnect();
+                }
+            }
+            catch {
+                // transient (offline / mint hiccup) — a later trigger retries.
+            }
+        };
+        // Comfortably inside the 15m `ek_` TTL; a missed (background-throttled) tick
+        // is recovered by the next, or by the reactive probe.
+        const REFRESH_INTERVAL_MS = 10 * 60 * 1000;
+        const timer = setInterval(() => void refresh(), REFRESH_INTERVAL_MS);
+        const teardowns = [() => clearInterval(timer)];
+        if (typeof window !== 'undefined') {
+            const onTrigger = () => void refresh();
+            window.addEventListener('online', onTrigger);
+            // OS-wake: the desktop shell bridges Electron `powerMonitor` 'resume' to
+            // this DOM event (visibilitychange does NOT fire on wake-from-sleep, so a
+            // nap longer than the TTL would otherwise leave a dead key untouched).
+            window.addEventListener('ablo:wake', onTrigger);
+            teardowns.push(() => window.removeEventListener('online', onTrigger));
+            teardowns.push(() => window.removeEventListener('ablo:wake', onTrigger));
+        }
+        if (typeof document !== 'undefined') {
+            const onVisible = () => {
+                if (document.visibilityState === 'visible')
+                    void refresh();
+            };
+            document.addEventListener('visibilitychange', onVisible);
+            teardowns.push(() => document.removeEventListener('visibilitychange', onVisible));
+        }
+        this.credentialLifecycleTeardown = () => {
+            for (const t of teardowns)
+                t();
+        };
+    }
+    /** Tear down the proactive credential lifecycle (idempotent). */
+    stopCredentialLifecycle() {
+        this.credentialLifecycleTeardown?.();
+        this.credentialLifecycleTeardown = null;
+    }
     // ── Sync Group Management ────────────────────────────────────────────────
     /**
      * Handle an actionType 'G' delta.
@@ -966,10 +1131,14 @@ export class BaseSyncedStore {
     createConnectionManager(kind) {
         if (kind === 'agent')
             return null;
-        return new ConnectionManager({ baseUrl: this._syncServerUrl });
+        return new ConnectionManager({
+            baseUrl: this._syncServerUrl,
+            getAuthToken: () => this.auth?.getAuthToken() ?? this.syncWebSocket?.getAuthToken() ?? null,
+        });
     }
     /** Disconnect and clean up all resources */
     async disconnect() {
+        this.stopCredentialLifecycle();
         if (this.batchTimer) {
             clearTimeout(this.batchTimer);
             this.batchTimer = null;
@@ -1095,6 +1264,7 @@ export class BaseSyncedStore {
             versions: this.versionVector,
             kind: context.kind,
             capabilityToken: context.capabilityToken,
+            getAuthToken: this.auth?.getAuthToken,
             capabilities: {
                 partialBootstrap: true,
                 compressedDeltas: true,
@@ -1213,6 +1383,7 @@ export class BaseSyncedStore {
             };
             manager.start({
                 onReconnect: () => this.performReconnect(),
+                onRefreshCredential: () => this.performCredentialRefresh(),
                 onSessionExpired: () => {
                     const err = new SyncSessionError('Session expired');
                     for (const listener of this.sessionErrorListeners) {
@@ -1249,10 +1420,13 @@ export class BaseSyncedStore {
                             }
                             break;
                         case 'probing_network':
+                        case 'refreshing_credential':
                         case 'reconnecting':
                         case 'backoff':
                             // Active recovery — the UI should reflect that the FSM
-                            // is doing work, not that we've given up.
+                            // is doing work, not that we've given up. (Re-minting a stale
+                            // access key is just another recovery step, surfaced the same
+                            // way; the user never sees a credential-level distinction.)
                             if (this.syncStatus.state !== 'reconnecting') {
                                 this.updateSyncStatus({ state: 'reconnecting' });
                             }

package/dist/Model.d.ts

@@ -212,10 +212,52 @@ export declare abstract class Model {
      * Prepare unarchive operation
      */
     prepareUnarchive(): ModelChanges;
+    /**
+     * Safely assign each field of `data` onto this instance, skipping `id`,
+     * unknown keys, MobX computed accessors, and getter-only (read-only)
+     * properties, and coercing date fields. Shared by `updateFromData`
+     * (hydration) and `applyChanges` (local user update).
+     *
+     * Change tracking is EXPLICIT, not magic: for every field actually
+     * written, `onWrite(key, oldValue, newValue)` is invoked with the value
+     * captured immediately before assignment. `applyChanges` passes a hook
+     * that records the change in `modifiedProperties`; `updateFromData`
+     * passes none (hydration must not generate outbound mutations). This
+     * is the single source of mutation tracking now that the `mobx-setup`
+     * `observe()` bridge has been removed (one write path: the SDK proxy).
+     */
+    private assignFieldsFromData;
     /**
      * Update from raw data (hydration)
+     *
+     * Used for inbound server deltas and pool upserts. Change tracking is
+     * deliberately suppressed: hydration writes must NOT land in
+     * `modifiedProperties`, otherwise applying a server delta would queue a
+     * brand-new outbound mutation and the record would echo forever. For a
+     * LOCAL user edit, use `applyChanges` instead.
+     *
+     * Suppression is belt-and-suspenders: we pass no `onWrite` hook AND
+     * clear/restore `modifiedProperties` around the assignment, so any
+     * remaining `mobx-setup` `observe()` side-channel writes are discarded
+     * too. (The clear/restore is a harmless no-op once that bridge is gone.)
      */
     updateFromData(data: ModelData): void;
+    /**
+     * Apply a LOCAL user-initiated update from a data object — the write
+     * path for `proxy.update({ id, data })`, which is the ONE AND ONLY way
+     * application code mutates synced fields.
+     *
+     * Unlike `updateFromData` (hydration, untracked), this records every
+     * written field in `modifiedProperties` via `propertyChanged`, so
+     * `getChanges()` / the transaction queue send the edited fields to the
+     * server and the undo system gets a correct pre-write baseline.
+     * Recording is EXPLICIT here (via the `onWrite` hook) — it does not rely
+     * on any MobX `observe()` side-channel.
+     *
+     * `_originalData` is intentionally NOT reset here: it stays as the
+     * last-persisted baseline until `clearChanges()` runs on sync-ack.
+     */
+    applyChanges(data: ModelData): void;
     /**
      * Serialize to JSON
      * This method should not trigger MobX reactions since it's used for serialization

package/dist/Model.js

@@ -357,8 +357,81 @@ export class Model {
             timestamp: new Date(),
         };
     }
+    /**
+     * Safely assign each field of `data` onto this instance, skipping `id`,
+     * unknown keys, MobX computed accessors, and getter-only (read-only)
+     * properties, and coercing date fields. Shared by `updateFromData`
+     * (hydration) and `applyChanges` (local user update).
+     *
+     * Change tracking is EXPLICIT, not magic: for every field actually
+     * written, `onWrite(key, oldValue, newValue)` is invoked with the value
+     * captured immediately before assignment. `applyChanges` passes a hook
+     * that records the change in `modifiedProperties`; `updateFromData`
+     * passes none (hydration must not generate outbound mutations). This
+     * is the single source of mutation tracking now that the `mobx-setup`
+     * `observe()` bridge has been removed (one write path: the SDK proxy).
+     */
+    assignFieldsFromData(data, onWrite) {
+        // Update properties with safety checks for read-only/computed accessors
+        for (const [key, raw] of Object.entries(data)) {
+            if (key === 'id')
+                continue;
+            // Only attempt to set if the property exists on instance or prototype
+            if (!(this.hasOwnProperty(key) || key in this))
+                continue;
+            // Never assign to MobX computed properties (they may expose a setter that throws)
+            try {
+                if (isComputedProp(this, key)) {
+                    continue;
+                }
+            }
+            catch {
+                // If MobX internals are unavailable for some reason, fall back to descriptor checks below
+            }
+            // Resolve property descriptor from own or prototype chain
+            const ownDesc = Object.getOwnPropertyDescriptor(this, key);
+            let desc = ownDesc;
+            if (!desc) {
+                let proto = Object.getPrototypeOf(this);
+                while (proto && proto !== Object.prototype && !desc) {
+                    desc = Object.getOwnPropertyDescriptor(proto, key);
+                    proto = Object.getPrototypeOf(proto);
+                }
+            }
+            // Determine writability: allow if data descriptor writable, or accessor with setter
+            const writable = desc
+                ? ('writable' in desc && !!desc.writable) ||
+                    ('set' in desc && typeof desc.set === 'function')
+                : true;
+            if (!writable) {
+                // Skip read-only accessor properties (getter-only)
+                continue;
+            }
+            // Handle date conversions
+            const value = (key === 'createdAt' || key === 'updatedAt' || key === 'archivedAt') && raw
+                ? new Date(raw)
+                : raw;
+            // Capture the pre-write value BEFORE assignment so trackers
+            // (undo inverse, getChanges) see the true previous value.
+            const oldValue = onWrite ? this[key] : undefined;
+            // Dynamic property assignment - use indexed access
+            this[key] = value;
+            onWrite?.(key, oldValue, value);
+        }
+    }
     /**
      * Update from raw data (hydration)
+     *
+     * Used for inbound server deltas and pool upserts. Change tracking is
+     * deliberately suppressed: hydration writes must NOT land in
+     * `modifiedProperties`, otherwise applying a server delta would queue a
+     * brand-new outbound mutation and the record would echo forever. For a
+     * LOCAL user edit, use `applyChanges` instead.
+     *
+     * Suppression is belt-and-suspenders: we pass no `onWrite` hook AND
+     * clear/restore `modifiedProperties` around the assignment, so any
+     * remaining `mobx-setup` `observe()` side-channel writes are discarded
+     * too. (The clear/restore is a harmless no-op once that bridge is gone.)
      */
     updateFromData(data) {
         if (this.isDisposed) {
@@ -367,52 +440,10 @@ export class Model {
             });
         }
         runInAction(() => {
-            // Temporarily disable change tracking
             const originalTracking = this.modifiedProperties;
             this.modifiedProperties = new Map();
-            // Update properties with safety checks for read-only/computed accessors
-            for (const [key, raw] of Object.entries(data)) {
-                if (key === 'id')
-                    continue;
-                // Only attempt to set if the property exists on instance or prototype
-                if (!(this.hasOwnProperty(key) || key in this))
-                    continue;
-                // Never assign to MobX computed properties (they may expose a setter that throws)
-                try {
-                    if (isComputedProp(this, key)) {
-                        continue;
-                    }
-                }
-                catch {
-                    // If MobX internals are unavailable for some reason, fall back to descriptor checks below
-                }
-                // Resolve property descriptor from own or prototype chain
-                const ownDesc = Object.getOwnPropertyDescriptor(this, key);
-                let desc = ownDesc;
-                if (!desc) {
-                    let proto = Object.getPrototypeOf(this);
-                    while (proto && proto !== Object.prototype && !desc) {
-                        desc = Object.getOwnPropertyDescriptor(proto, key);
-                        proto = Object.getPrototypeOf(proto);
-                    }
-                }
-                // Determine writability: allow if data descriptor writable, or accessor with setter
-                const writable = desc
-                    ? ('writable' in desc && !!desc.writable) ||
-                        ('set' in desc && typeof desc.set === 'function')
-                    : true;
-                if (!writable) {
-                    // Skip read-only accessor properties (getter-only)
-                    continue;
-                }
-                // Handle date conversions
-                const value = (key === 'createdAt' || key === 'updatedAt' || key === 'archivedAt') && raw
-                    ? new Date(raw)
-                    : raw;
-                // Dynamic property assignment for hydration - use indexed access
-                this[key] = value;
-            }
-            // Restore change tracking
+            // No `onWrite` → this call records nothing itself.
+            this.assignFieldsFromData(data);
             this.modifiedProperties = originalTracking;
         });
         // Mark as persisted if updating existing model
@@ -421,6 +452,34 @@ export class Model {
         }
         this.didUpdate();
     }
+    /**
+     * Apply a LOCAL user-initiated update from a data object — the write
+     * path for `proxy.update({ id, data })`, which is the ONE AND ONLY way
+     * application code mutates synced fields.
+     *
+     * Unlike `updateFromData` (hydration, untracked), this records every
+     * written field in `modifiedProperties` via `propertyChanged`, so
+     * `getChanges()` / the transaction queue send the edited fields to the
+     * server and the undo system gets a correct pre-write baseline.
+     * Recording is EXPLICIT here (via the `onWrite` hook) — it does not rely
+     * on any MobX `observe()` side-channel.
+     *
+     * `_originalData` is intentionally NOT reset here: it stays as the
+     * last-persisted baseline until `clearChanges()` runs on sync-ack.
+     */
+    applyChanges(data) {
+        if (this.isDisposed) {
+            throw new AbloValidationError('Cannot update disposed model', {
+                code: 'model_disposed',
+            });
+        }
+        runInAction(() => {
+            this.assignFieldsFromData(data, (key, oldValue, newValue) => {
+                this.propertyChanged(key, oldValue, newValue);
+            });
+        });
+        this.didUpdate();
+    }
     /**
      * Serialize to JSON
      * This method should not trigger MobX reactions since it's used for serialization

package/dist/SyncEngineContext.d.ts

@@ -33,7 +33,8 @@ export declare const noopObservability: SyncObservabilityProvider;
 export declare const noopAnalytics: SyncAnalytics;
 /** Browser-native online status provider */
 export declare const browserOnlineStatus: OnlineStatusProvider;
-/** Permissive session error detector — treats 401/403 as session errors */
+/** Session error detector — delegates to SyncSessionError so detection is
+ *  code-aware (only genuine session/JWT expiry counts), not a blunt 401/403. */
 export declare const defaultSessionErrorDetector: SessionErrorDetector;
 /**
  * Fallback config used when the context is read before

package/dist/SyncEngineContext.js

@@ -4,6 +4,7 @@
  * All SDK classes receive this context at construction time.
  * It bundles every injectable dependency so constructors stay clean.
  */
+import { SyncSessionError } from './errors.js';
 // ─────────────────────────────────────────────
 // No-op defaults for optional dependencies
 // ─────────────────────────────────────────────
@@ -45,7 +46,8 @@ export const browserOnlineStatus = {
         return typeof navigator !== 'undefined' ? navigator.onLine : true;
     },
 };
-/** Permissive session error detector — treats 401/403 as session errors */
+/** Session error detector — delegates to SyncSessionError so detection is
+ *  code-aware (only genuine session/JWT expiry counts), not a blunt 401/403. */
 export const defaultSessionErrorDetector = {
     isSessionError(error) {
         if (error && typeof error === 'object' && 'isSessionError' in error) {
@@ -53,8 +55,8 @@ export const defaultSessionErrorDetector = {
         }
         return false;
     },
-    isSessionErrorResponse(status) {
-        return status === 401 || status === 403;
+    isSessionErrorResponse(status, body) {
+        return SyncSessionError.isSessionErrorResponse(status, body);
     },
 };
 /**

package/dist/agent/session.js

@@ -20,6 +20,7 @@
  * The helper itself imports nothing app-specific. Open-source-clean.
  */
 import { Ablo } from '../client/Ablo.js';
+import { AbloConnectionError } from '../errors.js';
 /**
  * Returns a session whose `getAgent` method handles cache, mint,
  * sync_groups alignment, and lifecycle. Call `disposeAll()` from
@@ -68,9 +69,9 @@ export function createAgentSession(options) {
         // `AbloOptions` exposes the URL as `baseURL` (resolved by
         // `resolveBaseURL`). Earlier code passed `url:` here — `Ablo()`
         // silently dropped the unknown field (the cast below masked the
-        // type error) and `resolveBaseURL` fell through to the hardcoded
-        // default `wss://api.ablo.cloud` (now `wss://mesh.ablo.finance`).
-        // Staging surfaced the bug 2026-05-07 — DNS lookup hit the wrong
+        // type error) and `resolveBaseURL` fell through to the hosted
+        // default `wss://api.abloatai.com`. Staging surfaced the bug
+        // 2026-05-07 — DNS lookup hit the wrong
         // host even though the caller threaded `syncServerUrl` through
         // correctly. Forward as `baseURL` so the caller's URL is the only
         // source of truth and the package default never silently applies.
@@ -113,8 +114,8 @@ export function createAgentSession(options) {
                 causeMsg,
                 err,
             });
-            throw new Error(`ws bootstrap ${wsUrl} failed: ${e.message ?? 'bootstrap failed'}` +
-                (code ? ` (${code})` : ''));
+            throw new AbloConnectionError(`ws bootstrap ${wsUrl} failed: ${e.message ?? 'bootstrap failed'}` +
+                (code ? ` (${code})` : ''), { code: 'bootstrap_fetch_timeout', cause: err });
         }
         cacheByKey.set(key, { agent, expiresAtMs: minted.expiresAtMs });
         return agent;

package/dist/ai-sdk/coordination-context.js

@@ -80,17 +80,21 @@ function formatCoordinationNote(claims, target) {
     const entityLabel = target.entityType.toLowerCase();
     if (claims.length === 1) {
         const c = claims[0];
+        const details = c.description ? `Declared work: ${c.description}. ` : '';
         return (`<multiplayer_context>\n` +
             `Another participant is currently editing this ${entityLabel}. ` +
             `Action declared: ${c.reason}. ` +
+            details +
             `Defer to their concurrent changes when reasonable, or note your work as complementary to theirs. ` +
             `Avoid stomping their in-flight edits.\n` +
             `</multiplayer_context>`);
     }
     const actions = Array.from(new Set(claims.map((c) => c.reason))).join(', ');
+    const descriptions = Array.from(new Set(claims.map((c) => c.description).filter(Boolean))).join('; ');
     return (`<multiplayer_context>\n` +
         `${claims.length} other participants are currently editing this ${entityLabel}. ` +
         `Active actions: ${actions}. ` +
+        (descriptions ? `Declared work: ${descriptions}. ` : '') +
         `Coordinate with their in-flight work — defer where reasonable, ` +
         `or describe your work as complementary.\n` +
         `</multiplayer_context>`);