@agent-native/core 0.221.0 → 0.222.0-nightly-20261028092719

package/dist/client/embed-auth.js

@@ -2,20 +2,20 @@ import { EMBED_MODE_QUERY_PARAM, EMBED_START_PATH, EMBED_TARGET_HEADER, EMBED_TA
 import { isMcpDirectoryWidgetReadCapabilityScope, isMcpDirectoryWidgetWriteCapabilityScope, } from "../shared/embed-auth.js";
 import { FRAMEWORK_INTERNAL_ROUTE_PREFIX } from "../shared/framework-route-prefix.js";
 import { MCP_APP_HOST_FILL_ATTRIBUTE } from "../shared/mcp-app-display.js";
-import { EMBED_TOKEN_STORAGE_KEY, MCP_CHAT_BRIDGE_STORAGE_KEY, } from "../shared/mcp-app-widget-embed.js";
+import { embedTokenStorageKey, mcpChatBridgeStorageKey, } from "../shared/mcp-app-widget-embed.js";
 import { SIGN_IN_ENTRY_PATH, SIGN_IN_LEGACY_ENTRY_PATH, } from "../shared/sign-in-journey.js";
-import { frameworkRoutePrefix } from "./api-path.js";
+import { frameworkRoutePrefix, isWorkspaceRuntime, resolveAppBasePath, resolveExternalEmbedTargetAppBasePath, WorkspaceAppMountResolutionError, } from "./api-path.js";
 let installed = false;
-let memoryToken = null;
+const memoryTokens = new Map();
 let renewedFromUrlToken = null;
 let pendingWidgetSessionRenewal = null;
 let widgetSessionRenewalRequestId = 0;
 let mcpChatBridgeActive = false;
 let mcpChatBridgeScope = null;
+let mcpChatBridgeStorageKeyAtState = null;
 const AUTH_FAILURE_COOLDOWN_MS = 60_000;
 const GUARDED_METHODS = new Set(["GET", "HEAD"]);
 const AUTH_FAILURE_HEADER = "x-agent-native-auth-circuit-breaker";
-const EMBED_TOKEN_RENEWED_FROM_STORAGE_KEY = `${EMBED_TOKEN_STORAGE_KEY}:renewed-from`;
 const EMBED_SESSION_RENEWAL_TIMEOUT_MS = 15_000;
 const MCP_CHAT_BRIDGE_VIEWPORT_STYLE_ID = "agent-native-mcp-chat-bridge-viewport";
 const MCP_CHAT_BRIDGE_VIEWPORT_HEIGHT = 560;
@@ -24,6 +24,48 @@ const authFailureCache = new Map();
 function browserWindow() {
     return typeof window === "undefined" ? null : window;
 }
+function currentEmbedBasePath() {
+    try {
+        return resolveAppBasePath();
+    }
+    catch (error) {
+        if (error instanceof WorkspaceAppMountResolutionError)
+            return null;
+        throw error;
+    }
+}
+function currentEmbedTokenStorageKey() {
+    const basePath = currentEmbedBasePath();
+    return basePath === null
+        ? null
+        : embedTokenStorageKey(basePath, isWorkspaceRuntime());
+}
+function currentMcpChatBridgeStorageKey() {
+    const basePath = currentEmbedBasePath();
+    return basePath === null
+        ? null
+        : mcpChatBridgeStorageKey(basePath, isWorkspaceRuntime());
+}
+function memoryTokenFor(storageKey) {
+    return memoryTokens.get(storageKey) ?? null;
+}
+function externalEmbedToken(win) {
+    const config = win.__AGENT_NATIVE_EXTERNAL_EMBED;
+    return typeof config?.token === "string" && config.token
+        ? config.token
+        : null;
+}
+function externalEmbedTokenStorageKey(win) {
+    const config = win.__AGENT_NATIVE_EXTERNAL_EMBED;
+    const target = config?.target;
+    if (typeof target !== "string" || !target.startsWith("/"))
+        return null;
+    const workspaceRuntime = isWorkspaceRuntime();
+    const basePath = resolveExternalEmbedTargetAppBasePath(target);
+    if (workspaceRuntime && basePath === undefined)
+        return null;
+    return embedTokenStorageKey(basePath, workspaceRuntime);
+}
 function currentUrl(win) {
     try {
         return new URL(win.location.href);
@@ -48,13 +90,20 @@ export function readEmbedMcpChatBridgeFlagFromUrl() {
     return value === "1" || value === "true";
 }
 function currentMcpChatBridgeScope(win) {
-    return getEmbedAuthToken() ?? memoryToken ?? storedToken(win);
+    const storageKey = currentEmbedTokenStorageKey();
+    if (storageKey === null)
+        return null;
+    return getEmbedAuthToken() ?? storedToken(win, storageKey);
 }
 function clearMcpChatBridge(win) {
     mcpChatBridgeActive = false;
     mcpChatBridgeScope = null;
+    mcpChatBridgeStorageKeyAtState = null;
+    const storageKey = currentMcpChatBridgeStorageKey();
+    if (storageKey === null)
+        return;
     try {
-        win.sessionStorage?.removeItem(MCP_CHAT_BRIDGE_STORAGE_KEY);
+        win.sessionStorage.removeItem(storageKey);
     }
     catch {
         // ignore unavailable session storage
@@ -62,15 +111,19 @@ function clearMcpChatBridge(win) {
 }
 export function markEmbedMcpChatBridgeActive() {
     const win = browserWindow();
-    const scope = win ? currentMcpChatBridgeScope(win) : null;
+    const storageKey = currentMcpChatBridgeStorageKey();
+    const scope = win && storageKey !== null ? currentMcpChatBridgeScope(win) : null;
     mcpChatBridgeActive = true;
     mcpChatBridgeScope = scope;
+    mcpChatBridgeStorageKeyAtState = storageKey;
+    if (storageKey === null)
+        return;
     try {
         if (scope) {
-            win?.sessionStorage?.setItem(MCP_CHAT_BRIDGE_STORAGE_KEY, scope);
+            win?.sessionStorage.setItem(storageKey, scope);
         }
         else {
-            win?.sessionStorage?.removeItem(MCP_CHAT_BRIDGE_STORAGE_KEY);
+            win?.sessionStorage.removeItem(storageKey);
         }
     }
     catch {
@@ -82,6 +135,23 @@ export function isEmbedMcpChatBridgeActive() {
     const win = browserWindow();
     if (!win)
         return false;
+    const storageKey = currentMcpChatBridgeStorageKey();
+    if (storageKey === null) {
+        if (isEmbedAuthActive() && readEmbedMcpChatBridgeFlagFromUrl()) {
+            markEmbedMcpChatBridgeActive();
+        }
+        // A temporary route without a declared mount does not prove the host
+        // unenrolled this document from the bridge.
+        return mcpChatBridgeActive;
+    }
+    if (mcpChatBridgeActive && mcpChatBridgeStorageKeyAtState === null) {
+        markEmbedMcpChatBridgeActive();
+    }
+    if (mcpChatBridgeActive && mcpChatBridgeStorageKeyAtState !== storageKey) {
+        mcpChatBridgeActive = false;
+        mcpChatBridgeScope = null;
+        mcpChatBridgeStorageKeyAtState = null;
+    }
     if (!isEmbedAuthActive()) {
         clearMcpChatBridge(win);
         return false;
@@ -108,14 +178,15 @@ export function isEmbedMcpChatBridgeActive() {
         return false;
     }
     try {
-        const storedScope = win.sessionStorage?.getItem(MCP_CHAT_BRIDGE_STORAGE_KEY);
+        const storedScope = win.sessionStorage.getItem(storageKey);
         if (storedScope && (scope == null || storedScope === scope)) {
             mcpChatBridgeActive = true;
             mcpChatBridgeScope = storedScope;
+            mcpChatBridgeStorageKeyAtState = storageKey;
             return true;
         }
         if (storedScope && scope != null && storedScope !== scope) {
-            win.sessionStorage?.removeItem(MCP_CHAT_BRIDGE_STORAGE_KEY);
+            win.sessionStorage.removeItem(storageKey);
         }
         return false;
     }
@@ -123,18 +194,46 @@ export function isEmbedMcpChatBridgeActive() {
         return false;
     }
 }
-function storedToken(win) {
+function storedToken(win, storageKey) {
     try {
-        return win.sessionStorage?.getItem(EMBED_TOKEN_STORAGE_KEY) ?? null;
+        return win.sessionStorage.getItem(storageKey) ?? null;
     }
     catch {
         return null;
     }
 }
-function storeToken(token, win) {
-    memoryToken = token;
+function embedTokenTargetStorageKey(token) {
+    const payload = token.split(".")[0] ?? "";
+    let decodedClaims;
     try {
-        win.sessionStorage?.setItem(EMBED_TOKEN_STORAGE_KEY, token);
+        const base64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+        const bytes = Uint8Array.from(atob(base64 + "=".repeat((4 - (base64.length % 4)) % 4)), (char) => char.charCodeAt(0));
+        decodedClaims = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        // coercion-ok: an unreadable token has no mount binding; null makes the caller reject it.
+        return null;
+    }
+    if (!decodedClaims ||
+        typeof decodedClaims !== "object" ||
+        Array.isArray(decodedClaims)) {
+        return null;
+    }
+    const claims = decodedClaims;
+    if (typeof claims.audienceBasePath === "string") {
+        return embedTokenStorageKey(claims.audienceBasePath, true);
+    }
+    if (claims.audienceBasePath !== undefined)
+        return null;
+    if (typeof claims.targetPath !== "string")
+        return null;
+    const basePath = resolveExternalEmbedTargetAppBasePath(claims.targetPath);
+    return basePath === undefined ? null : embedTokenStorageKey(basePath, true);
+}
+function storeToken(token, win, storageKey) {
+    memoryTokens.set(storageKey, token);
+    try {
+        win.sessionStorage.setItem(storageKey, token);
     }
     catch {
         // Session storage may be unavailable in some sandboxed hosts. The
@@ -145,37 +244,56 @@ export function getEmbedAuthToken() {
     const win = browserWindow();
     if (!win)
         return null;
+    const storageKey = currentEmbedTokenStorageKey();
+    if (storageKey === null)
+        return null;
+    const renewedFromStorageKey = `${storageKey}:renewed-from`;
     const fromUrl = readTokenFromUrl(win);
     if (fromUrl) {
+        if (isWorkspaceRuntime() &&
+            embedTokenTargetStorageKey(fromUrl) !== storageKey) {
+            return null;
+        }
         let renewedFrom = renewedFromUrlToken;
         if (!renewedFrom) {
             try {
-                renewedFrom =
-                    win.sessionStorage?.getItem(EMBED_TOKEN_RENEWED_FROM_STORAGE_KEY) ??
-                        null;
+                renewedFrom = win.sessionStorage.getItem(renewedFromStorageKey) ?? null;
             }
             catch {
                 renewedFrom = null;
             }
         }
         if (renewedFrom === fromUrl) {
-            const refreshed = memoryToken ?? storedToken(win);
+            const refreshed = memoryTokenFor(storageKey) ?? storedToken(win, storageKey);
             if (refreshed && refreshed !== fromUrl)
                 return refreshed;
         }
         if (renewedFrom && renewedFrom !== fromUrl) {
             renewedFromUrlToken = null;
             try {
-                win.sessionStorage?.removeItem(EMBED_TOKEN_RENEWED_FROM_STORAGE_KEY);
+                win.sessionStorage.removeItem(renewedFromStorageKey);
             }
             catch {
                 // coercion-ok: cleanup is best-effort; the refreshed URL token still supersedes this marker.
             }
         }
-        storeToken(fromUrl, win);
+        storeToken(fromUrl, win, storageKey);
         return fromUrl;
     }
-    return memoryToken ?? storedToken(win);
+    const inMemoryToken = memoryTokenFor(storageKey);
+    if (inMemoryToken)
+        return inMemoryToken;
+    const stored = storedToken(win, storageKey);
+    if (stored)
+        return stored;
+    const external = externalEmbedToken(win);
+    if (!external)
+        return null;
+    // The frame config outlives navigation, but its token belongs to one mount.
+    if (externalEmbedTokenStorageKey(win) !== storageKey)
+        return null;
+    storeToken(external, win, storageKey);
+    return external;
 }
 function readEmbedTokenScope(token) {
     const payload = token.split(".")[0] ?? "";
@@ -362,13 +480,14 @@ export function _resetEmbedAuthForTests() {
             pending.win.clearTimeout(id);
     }
     installed = false;
-    memoryToken = null;
+    memoryTokens.clear();
     renewedFromUrlToken = null;
     pendingWidgetSessionRenewal = null;
     widgetSessionRenewalRequestId = 0;
     widgetScopeCache = null;
     mcpChatBridgeActive = false;
     mcpChatBridgeScope = null;
+    mcpChatBridgeStorageKeyAtState = null;
     authFailureCache.clear();
 }
 /**
@@ -654,8 +773,8 @@ export function ensureEmbedAuthFetchInterceptor() {
         markEmbedMcpChatBridgeActive();
     const urlToken = readTokenFromUrl(win);
     if (urlToken) {
-        getEmbedAuthToken();
-        stripTokenFromUrl(win);
+        if (getEmbedAuthToken())
+            stripTokenFromUrl(win);
     }
     ensureMcpChatBridgeViewportClamp(win);
     if (installed)

package/dist/client/route-state.js

@@ -3,7 +3,7 @@ import { useCallback, useEffect, useMemo, useRef } from "react";
 import { useLocation, useNavigate, } from "react-router";
 import { isWorkspaceAppPath } from "./api-path.js";
 import { deleteClientAppState, readClientAppState, setClientAppState, } from "./application-state.js";
-import { getBrowserTabId } from "./browser-tab-id.js";
+import { getBrowserTabId, isBrowserTabIdForCurrentDocument, } from "./browser-tab-id.js";
 import { navigateWithAgentChatViewTransition, } from "./chat-view-transition.js";
 import { postAgentNativeWorkspaceAppRoute } from "./workspace-app-navigation.js";
 const SAFE_BROWSER_TAB_ID_RE = /^[A-Za-z0-9_-]{1,96}$/;
@@ -195,8 +195,19 @@ export function useAgentRouteState(options) {
     const { navigationKey = "navigation", commandKey = "navigate" } = options;
     const location = useLocation();
     const navigate = useNavigate();
-    const browserTabId = useMemo(() => normalizeBrowserTabId(options.browserTabId) ??
-        (options.browserTabId === undefined ? defaultBrowserTabId() : undefined), [options.browserTabId]);
+    const defaultTabId = defaultBrowserTabId();
+    const explicitTabId = normalizeBrowserTabId(options.browserTabId);
+    // Templates expose TAB_ID as a module-level constant. If it matches the
+    // current document's generated IDs, keep following the active mount.
+    const browserTabId = explicitTabId === undefined ||
+        isBrowserTabIdForCurrentDocument(explicitTabId)
+        ? defaultTabId
+        : explicitTabId;
+    const requestSourceFollowsDefault = options.requestSource === undefined ||
+        isBrowserTabIdForCurrentDocument(options.requestSource);
+    const requestSource = requestSourceFollowsDefault
+        ? browserTabId
+        : options.requestSource;
     const writeGlobalNavigation = options.writeGlobalNavigation ?? false;
     const readGlobalCommandFallback = options.readGlobalCommandFallback ?? false;
     useEffect(() => {
@@ -237,7 +248,7 @@ export function useAgentRouteState(options) {
         commandKeys,
         commandQueryKey,
         browserTabId,
-        requestSource: options.requestSource ?? browserTabId,
+        requestSource,
         commandRefetchInterval: options.refetchInterval,
         enabled: options.enabled,
         keepalive: options.keepalive,

package/dist/client/sse-event-processor.js

@@ -3,6 +3,7 @@ import { BUILDER_GATEWAY_INTERNAL_ERROR_CODE, PROVIDER_TRANSIENT_REJECTION_ERROR
 import { normalizeConnectRequiredResult } from "../shared/connect-required.js";
 import { isNonProgressEventType } from "../shared/progress-events.js";
 import { toolInputsMatch } from "../shared/tool-inputs.js";
+import { getBrowserTabId } from "./browser-tab-id.js";
 import { emitChatFirstOpenApp } from "./chat-first-state.js";
 import { formatChatErrorText, normalizeChatError } from "./error-format.js";
 import { humanizeToolLabelText, humanizeToolName, isToolCallActive, runningToolLabel, } from "./tool-display.js";
@@ -1443,6 +1444,8 @@ export function processEvent(ev, content, toolCallCounter, tabId, state, context
                     isError: ev.isError === true,
                     completedSideEffect: ev.completedSideEffect === true,
                     tabId,
+                    browserTabId: getBrowserTabId(),
+                    runId: context?.runId,
                     eventId: ev.eventId ?? ev.id,
                 },
             }));

package/dist/client/use-change-version.js

@@ -87,7 +87,12 @@ class ChangeVersionStore {
         }
     }
 }
-const store = new ChangeVersionStore();
+const CHANGE_VERSION_STORE_SYMBOL = Symbol.for("@agent-native/core/client/change-version-store");
+const globalChangeVersionStore = globalThis;
+// Vite can load an optimized package root beside a directly served deep import.
+const store = globalChangeVersionStore[CHANGE_VERSION_STORE_SYMBOL] ??
+    (globalChangeVersionStore[CHANGE_VERSION_STORE_SYMBOL] =
+        new ChangeVersionStore());
 export function bumpChangeVersion(source, version) {
     return store.bump(source, version);
 }

package/dist/client/use-db-sync.js

@@ -5,7 +5,7 @@ export { REALTIME_CAP_POLL_LIVE } from "../realtime-protocol.js";
 import { addSurfaceVisibilityListener, isHostSurfaceHidden, isSurfaceHidden, } from "../shared/surface-visibility.js";
 import { actionQueryAffectedByResources } from "./action-query-scope.js";
 import { agentNativePath } from "./api-path.js";
-import { getBrowserTabId } from "./browser-tab-id.js";
+import { getBrowserTabId, resolveBrowserTabIdAlias } from "./browser-tab-id.js";
 import { isTerminalAuthFailure } from "./create-query-client.js";
 import { ensureEmbedAuthFetchInterceptor, isEmbedAuthActive, } from "./embed-auth.js";
 import { bumpChangeVersion, bumpActiveLocalChangeVersions, bumpLocalChangeVersion, } from "./use-change-version.js";
@@ -1372,10 +1372,7 @@ export function useDbSync(options = {}) {
                             .map((key) => `${key.length}:${key}`)
                             .join("|");
                         const needsBroadAppStateRefresh = appStateKeys.some((key) => key === "*" ||
-                            isInteractionCriticalSyncEvent({
-                                source: "app-state",
-                                key,
-                            }));
+                            INTERACTION_CRITICAL_APP_STATE_KEYS.includes(key));
                         invalidateWithoutCancel(needsBroadAppStateRefresh
                             ? { queryKey: ["app-state"] }
                             : {
@@ -1432,11 +1429,19 @@ export function useDbSync(options = {}) {
                 subscriberCursor = maxSyncCursor(subscriberCursor, cursor);
         }
         const sideEffectToolsByTab = new Map();
-        const eventsForTool = (tool, completedSideEffect, failed) => {
+        const browserTabIdsByTab = new Map();
+        const eventsForTool = (tool, completedSideEffect, failed, browserTabId) => {
             const events = [];
             if (completedSideEffect) {
                 events.push({ source: "action", key: tool, version: 0 });
             }
+            if (tool === "navigate" && completedSideEffect) {
+                events.push({
+                    source: "app-state",
+                    key: browserTabId ? `navigate:${browserTabId}` : "navigate",
+                    version: 0,
+                });
+            }
             if (["__set_url__", "set-url", "set-search-params"].includes(tool)) {
                 events.push({ source: "app-state", key: "__set_url__", version: 0 });
             }
@@ -1478,13 +1483,36 @@ export function useDbSync(options = {}) {
                 return;
             const tool = detail.tool;
             const completedSideEffect = detail.completedSideEffect === true;
-            const events = eventsForTool(tool, completedSideEffect, detail.isError === true);
+            const tabId = typeof detail.tabId === "string" && detail.tabId
+                ? detail.tabId
+                : "__default__";
+            const runId = typeof detail.runId === "string" && detail.runId
+                ? detail.runId
+                : undefined;
+            const runStart = browserTabIdsByTab.get(tabId);
+            if (runId && runStart?.runId && runId !== runStart.runId)
+                return;
+            const aliasedRunStartId = runStart
+                ? resolveBrowserTabIdAlias(runStart.browserTabId)
+                : undefined;
+            const browserTabId = aliasedRunStartId ??
+                runStart?.browserTabId ??
+                (typeof detail.browserTabId === "string"
+                    ? detail.browserTabId
+                    : getBrowserTabId());
+            if (runStart && browserTabId !== runStart.browserTabId) {
+                browserTabIdsByTab.set(tabId, { ...runStart, browserTabId });
+            }
+            if (completedSideEffect && !runStart) {
+                browserTabIdsByTab.set(tabId, {
+                    browserTabId,
+                    ...(runId ? { runId } : {}),
+                });
+            }
+            const events = eventsForTool(tool, completedSideEffect, detail.isError === true, browserTabId);
             if (events.length === 0)
                 return;
             if (completedSideEffect) {
-                const tabId = typeof detail.tabId === "string" && detail.tabId
-                    ? detail.tabId
-                    : "__default__";
                 const tools = sideEffectToolsByTab.get(tabId) ?? new Map();
                 const previouslyFailed = tools.get(tool);
                 tools.set(tool, previouslyFailed === false ? false : detail.isError === true);
@@ -1498,6 +1526,22 @@ export function useDbSync(options = {}) {
                 const tabId = typeof detail.tabId === "string" && detail.tabId
                     ? detail.tabId
                     : "__default__";
+                const browserTabId = typeof detail.browserTabId === "string"
+                    ? detail.browserTabId
+                    : getBrowserTabId();
+                const runId = typeof detail.runId === "string" && detail.runId
+                    ? detail.runId
+                    : undefined;
+                const runStart = browserTabIdsByTab.get(tabId);
+                if (!runId) {
+                    browserTabIdsByTab.set(tabId, { browserTabId });
+                }
+                else if (!runStart || (runStart.runId && runStart.runId !== runId)) {
+                    browserTabIdsByTab.set(tabId, { browserTabId, runId });
+                }
+                else if (!runStart.runId) {
+                    browserTabIdsByTab.set(tabId, { ...runStart, runId });
+                }
                 sideEffectToolsByTab.delete(tabId);
                 return;
             }
@@ -1506,11 +1550,26 @@ export function useDbSync(options = {}) {
             const tabId = typeof detail.tabId === "string" && detail.tabId
                 ? detail.tabId
                 : "__default__";
+            const runStart = browserTabIdsByTab.get(tabId);
+            const runId = typeof detail.runId === "string" && detail.runId
+                ? detail.runId
+                : undefined;
+            if (runId && runStart?.runId && runId !== runStart.runId)
+                return;
+            const aliasedRunStartId = runStart
+                ? resolveBrowserTabIdAlias(runStart.browserTabId)
+                : undefined;
+            const browserTabId = aliasedRunStartId ??
+                runStart?.browserTabId ??
+                (typeof detail.browserTabId === "string"
+                    ? detail.browserTabId
+                    : getBrowserTabId());
+            browserTabIdsByTab.delete(tabId);
             const tools = sideEffectToolsByTab.get(tabId);
             if (!tools?.size)
                 return;
             sideEffectToolsByTab.delete(tabId);
-            applyRunEvents(event, [...tools].flatMap(([tool, failed]) => eventsForTool(tool, true, failed)), processedRunEndEvents);
+            applyRunEvents(event, [...tools].flatMap(([tool, failed]) => eventsForTool(tool, true, failed, browserTabId)), processedRunEndEvents);
         };
         window.addEventListener("agent-native:tool-done", handleRunToolDone);
         window.addEventListener("agentNative.chatRunning", handleRunStatus);

package/dist/collab/client.d.ts

@@ -18,6 +18,29 @@ export interface UseCollaborativeDocOptions {
     };
     /** Application events received alongside document updates on the existing transport. */
     onEvent?: (event: SyncEvent) => void;
+    /**
+     * Keeps this tab's unacknowledged updates in localStorage until the server
+     * acknowledges them, and sends the ones a closed or reloaded tab left
+     * behind when the doc next opens for the same user. Needs `user`, whose
+     * email scopes what is kept.
+     */
+    durableUpdates?: boolean;
+    /** New updates need a known live-copy outcome handled by a current strict subscriber. */
+    requireLiveCopyOutcome?: boolean;
+    /**
+     * Called for each update the server acknowledged, with the live-copy
+     * outcome it reported. With it, an acknowledgment whose body cannot be read
+     * counts as undelivered and the update is sent again.
+     */
+    onUpdateAcknowledged?: (ack: CollabUpdateAck) => void;
+}
+/**
+ * What the server reported for an acknowledged update: whether the app's rows
+ * were derived from its live copy, or null when the server defines none.
+ */
+export interface CollabUpdateAck {
+    liveCopy: "derived" | "not_derived" | "unchanged" | null;
+    liveCopyReason?: string;
 }
 export type CollabInitializationErrorCategory = "forbidden-or-not-found" | "server" | "network" | "invalid-payload";
 export type CollabInitializationState = {
@@ -51,6 +74,17 @@ export interface UseCollaborativeDocResult {
      * can already receive it through the document instead of inserting it twice.
      */
     flushUpdates: () => Promise<boolean>;
+    /**
+     * True once keeping this tab's unacknowledged updates, or reading the ones
+     * another tab left, failed. Updates still send while the tab stays open.
+     */
+    durableUpdatesFailed: boolean;
+    /**
+     * True once the server refused one of this tab's updates as too large.
+     * Resending it cannot succeed, so this tab stops sending updates; they stay
+     * unacknowledged, and kept with `durableUpdates`.
+     */
+    updatesRefused: boolean;
     activeUsers: CollabUser[];
     agentActive: boolean;
     agentPresent: boolean;