@turingfocus/chat-runtime 0.7.0 → 0.8.1

package/dist/chat-client.js

@@ -1,9 +1,12 @@
-import { answerInteractionInputSchema, createConversationInputSchema, createGatewayDeadlineExceededError, deleteConversationInputSchema, getAskUserInteractionAnswerValidationError, isGatewayDeadlineExceeded, isChatLifecycleOperable, isGatewayOperationSupported, listConversationsInputSchema, renameConversationInputSchema, } from "@turingfocus/chat-protocol";
+import { answerInteractionInputSchema, getTimelineItemKey, createConversationInputSchema, createGatewayDeadlineExceededError, deleteConversationInputSchema, getAskUserInteractionAnswerValidationError, isGatewayDeadlineExceeded, isChatLifecycleOperable, isGatewayOperationSupported, listConversationsInputSchema, renameConversationInputSchema, sendMessageInputSchema, } from "@turingfocus/chat-protocol";
 import { createGatewayNotificationQueue, } from "./gateway-notification-queue.js";
 import { cloneImmutable, deepEqual } from "./immutable.js";
 import { applySnapshotUpdate, applyRuntimeSnapshotError, createSnapshotState, rebaseSnapshotState, updateConversationId, updateSnapshotState, } from "./snapshot-state.js";
 import { SnapshotStore, } from "./snapshot-store.js";
-import { mergeHistoryTimeline } from "./timeline.js";
+import { createTimelineState, mergeHistoryTimeline } from "./timeline.js";
+import { ConversationCache, mergeCachedHistory, } from "./conversation-cache.js";
+import { cachedDisplaySnapshot } from "./cache-record.js";
+import { areComposerLongTextsValid, emptyComposerDraft, rebaseComposerLongTexts, resolveComposerDraftText, } from "./composer-draft.js";
 const runtimeFailure = (code, message, conversationId) => ({
     ok: false,
     error: cloneImmutable({
@@ -41,6 +44,19 @@ const runCleanup = async (cleanup, onError) => {
  */
 export class ChatClient {
     #gateway;
+    #cache;
+    #cacheListeners = new Set();
+    #cacheRequestId = 0;
+    #cacheReadOnly = false;
+    #cacheWriteScheduled = false;
+    #clearedSnapshot = null;
+    #cacheState = Object.freeze({
+        status: "idle",
+        source: "none",
+        freshness: "miss",
+        unavailableAttachments: 0,
+        storageError: false,
+    });
     #onUnhandledError;
     #snapshotStore;
     #disposed = false;
@@ -50,6 +66,10 @@ export class ChatClient {
     #generation = 0;
     #gatewaySubscription;
     #interactionAnswersInFlight = new Set();
+    #composerDrafts = new Map();
+    #composerListeners = new Set();
+    #composerSendsInFlight = new Map();
+    #messageSendsInFlight = new Map();
     #retiredInteractionIdentities = new Set();
     #supersededInteractionAnswers = new Set();
     #historyRequestId = 0;
@@ -61,12 +81,141 @@ export class ChatClient {
     #pendingHandoff;
     constructor(options) {
         this.#gateway = options.gateway;
+        this.#cache =
+            options.cache === false
+                ? undefined
+                : new ConversationCache({
+                    ...options.cache,
+                    onEvent: (event) => {
+                        if (event.kind === "storage-error" ||
+                            event.kind === "invalid-record" ||
+                            event.kind === "write-conflict")
+                            this.#setCacheState({
+                                ...this.#cacheState,
+                                storageError: true,
+                            });
+                        if (options.cache)
+                            options.cache.onEvent?.(event);
+                    },
+                }, (id) => {
+                    if (this.getSnapshot()?.conversation.id !== id)
+                        this.#discardComposerDraft(id);
+                });
+        if (this.#cache === undefined)
+            this.#cacheState = Object.freeze({
+                ...this.#cacheState,
+                status: "disabled",
+            });
         this.#onUnhandledError = options.onUnhandledError;
         this.#snapshotStore = new SnapshotStore({
             onListenerError: (cause) => {
                 this.#reportUnhandledError({ cause, source: "listener" });
             },
         });
+        if (options.cache !== false && options.cache?.storage !== undefined) {
+            this.#snapshotStore.subscribe(() => this.#scheduleCacheWrite());
+        }
+    }
+    getCacheState() {
+        return this.#cacheState;
+    }
+    subscribeCacheState(listener) {
+        const isDisposed = () => this.#disposed;
+        let closed = this.#disposed;
+        if (!closed)
+            this.#cacheListeners.add(listener);
+        return {
+            get closed() {
+                return closed || isDisposed();
+            },
+            dispose: () => {
+                closed = true;
+                this.#cacheListeners.delete(listener);
+            },
+        };
+    }
+    async clearConversationCache(conversationId, options) {
+        if (this.#disposed)
+            return;
+        if (this.#cacheState.conversationId === conversationId)
+            this.cancelPendingConversationLoad();
+        if (this.getSnapshot()?.conversation.id === conversationId)
+            this.#clearedSnapshot = this.getSnapshot();
+        this.#discardComposerDraft(conversationId);
+        const clearing = this.#cache?.clear(conversationId, options);
+        if (this.getSnapshot()?.conversation.id === conversationId)
+            this.#clearCachedView();
+        if (this.#cacheState.conversationId === conversationId)
+            this.#setCacheState({
+                ...this.#cacheState,
+                source: "none",
+                freshness: "miss",
+            });
+        await clearing;
+    }
+    async clearCache(options) {
+        if (this.#disposed)
+            return;
+        this.cancelPendingConversationLoad();
+        this.#clearedSnapshot = this.getSnapshot();
+        for (const id of [...this.#composerDrafts.keys()])
+            this.#discardComposerDraft(id);
+        const clearing = this.#cache?.clear(undefined, options);
+        this.#clearCachedView();
+        this.#setCacheState({
+            status: this.#cache === undefined ? "disabled" : "idle",
+            source: "none",
+            freshness: "miss",
+            unavailableAttachments: 0,
+            storageError: this.#cache?.storageError ?? false,
+        });
+        await clearing;
+    }
+    #clearCachedView() {
+        const snapshot = this.getSnapshot();
+        if (!this.#cacheReadOnly || snapshot === null)
+            return;
+        // Clearing local content does not delete the server conversation or selection.
+        this.#snapshotStore.commit(createSnapshotState(cachedDisplaySnapshot({
+            ...snapshot,
+            timeline: [],
+            pageInfo: { hasPreviousPage: false },
+        })));
+    }
+    async flushCache(options) {
+        this.#captureCache(options);
+        await this.#cache?.flush();
+    }
+    #captureCache(options) {
+        const snapshot = this.getSnapshot();
+        if (this.#disposed ||
+            this.#cacheReadOnly ||
+            snapshot === null ||
+            snapshot === this.#clearedSnapshot)
+            return;
+        this.#cache?.put(snapshot, this.getComposerDraft(snapshot.conversation.id), options);
+    }
+    #scheduleCacheWrite() {
+        if (this.#cacheWriteScheduled || this.#disposed || this.#cacheReadOnly)
+            return;
+        this.#cacheWriteScheduled = true;
+        void Promise.resolve().then(() => {
+            this.#cacheWriteScheduled = false;
+            this.#captureCache({ deadlineAt: Date.now() + 5000 });
+        });
+    }
+    #setCacheState(state) {
+        if (this.#disposed || this.#cache === undefined)
+            return;
+        this.#cacheState = Object.freeze(state);
+        for (const listener of this.#cacheListeners) {
+            try {
+                listener();
+            }
+            catch (cause) {
+                this.#reportUnhandledError({ cause, source: "listener" });
+            }
+        }
     }
     get disposed() {
         return this.#disposed;
@@ -81,12 +230,124 @@ export class ChatClient {
     subscribeState(listener) {
         return this.#snapshotStore.subscribeState(listener);
     }
+    getComposerDraft(conversationId) {
+        const existing = this.#composerDrafts.get(conversationId);
+        if (existing !== undefined)
+            return existing;
+        const empty = emptyComposerDraft(conversationId);
+        if (!this.#disposed)
+            this.#composerDrafts.set(conversationId, empty);
+        return empty;
+    }
+    #discardComposerDraft(conversationId) {
+        this.#composerDrafts.delete(conversationId);
+        const empty = emptyComposerDraft(conversationId);
+        for (const listener of this.#composerListeners) {
+            try {
+                listener(empty);
+            }
+            catch (cause) {
+                this.#reportUnhandledError({ cause, source: "listener" });
+            }
+        }
+    }
+    setComposerDraft(input) {
+        if (this.#disposed)
+            return this.getComposerDraft(input.conversationId);
+        const current = this.getComposerDraft(input.conversationId);
+        const nextText = input.text ?? current.text;
+        const nextLongTexts = input.longTexts ??
+            rebaseComposerLongTexts(current.text, nextText, current.longTexts);
+        if (!areComposerLongTextsValid(nextText, nextLongTexts)) {
+            throw new TypeError("Composer long-text anchors are invalid");
+        }
+        const next = cloneImmutable({
+            conversationId: input.conversationId,
+            text: nextText,
+            attachments: input.attachments ?? current.attachments,
+            longTexts: nextLongTexts,
+            revision: current.revision + 1,
+        });
+        this.#composerDrafts.set(input.conversationId, next);
+        this.#cache?.updateDraft(input.conversationId, next, {
+            deadlineAt: Date.now() + 5000,
+        }, input.attachments === undefined);
+        this.#scheduleCacheWrite();
+        for (const listener of this.#composerListeners) {
+            try {
+                listener(next);
+            }
+            catch (cause) {
+                this.#reportUnhandledError({ cause, source: "listener" });
+            }
+        }
+        return next;
+    }
+    subscribeComposerDraft(listener) {
+        if (this.#disposed)
+            return { closed: true, dispose: () => undefined };
+        this.#composerListeners.add(listener);
+        let active = true;
+        return {
+            get closed() {
+                return !active;
+            },
+            dispose: () => {
+                if (!active)
+                    return;
+                active = false;
+                this.#composerListeners.delete(listener);
+            },
+        };
+    }
+    async sendComposerDraft(input) {
+        const inFlightKey = input.clientMessageId === undefined
+            ? undefined
+            : `${input.conversationId.length}:${input.conversationId}:${input.clientMessageId}`;
+        if (inFlightKey !== undefined) {
+            const existing = this.#composerSendsInFlight.get(inFlightKey);
+            if (existing !== undefined)
+                return existing;
+        }
+        const draft = this.getComposerDraft(input.conversationId);
+        const operation = (async () => {
+            const result = await this.sendMessage({
+                conversationId: input.conversationId,
+                deadlineAt: input.deadlineAt,
+                text: resolveComposerDraftText(draft),
+                attachments: draft.attachments,
+                ...(input.clientMessageId === undefined
+                    ? {}
+                    : { clientMessageId: input.clientMessageId }),
+            });
+            if (result.ok && this.getComposerDraft(input.conversationId) === draft) {
+                this.setComposerDraft({
+                    conversationId: input.conversationId,
+                    text: "",
+                    attachments: [],
+                    longTexts: [],
+                });
+            }
+            return result;
+        })();
+        if (inFlightKey !== undefined) {
+            this.#composerSendsInFlight.set(inFlightKey, operation);
+            const clearInFlight = () => {
+                if (this.#composerSendsInFlight.get(inFlightKey) === operation) {
+                    this.#composerSendsInFlight.delete(inFlightKey);
+                }
+            };
+            void operation.then(clearInFlight, clearInFlight);
+        }
+        return operation;
+    }
     /**
      * Retires the current top-level conversation load without changing an
      * already committed snapshot. Once a snapshot commits, this is a no-op and
      * that load completes successfully while transport cleanup settles.
      */
     cancelPendingConversationLoad() {
+        this.#cacheRequestId += 1;
         if (this.#disposed || this.#pendingLoadRequestId === undefined)
             return;
         this.#loadRequestId += 1;
@@ -192,6 +453,25 @@ export class ChatClient {
             result.value.deletedConversationId !== parsed.data.conversationId) {
             return runtimeFailure("validation", "Gateway deleted a different conversation", parsed.data.conversationId);
         }
+        const cacheClear = result.ok
+            ? this.#cache
+                ?.clear(parsed.data.conversationId, parsed.data)
+                .catch(() => undefined)
+            : undefined;
+        if (result.ok) {
+            if (this.#cacheState.conversationId === parsed.data.conversationId)
+                this.#cacheRequestId += 1;
+            this.#discardComposerDraft(parsed.data.conversationId);
+            const sendKeyPrefix = `${parsed.data.conversationId.length}:${parsed.data.conversationId}:`;
+            for (const key of this.#composerSendsInFlight.keys()) {
+                if (key.startsWith(sendKeyPrefix))
+                    this.#composerSendsInFlight.delete(key);
+            }
+            for (const key of this.#messageSendsInFlight.keys()) {
+                if (key.startsWith(sendKeyPrefix))
+                    this.#messageSendsInFlight.delete(key);
+            }
+        }
         if (result.ok &&
             this.#pendingLoadConversationId === parsed.data.conversationId) {
             this.#loadRequestId += 1;
@@ -220,9 +500,144 @@ export class ChatClient {
             this.#snapshotStore.clear();
             await this.#runSubscriptionCleanup(() => subscription?.dispose(parsed.data), parsed.data.conversationId);
         }
+        await cacheClear;
         return result;
     }
     async loadConversation(input) {
+        if (this.#cache === undefined ||
+            input.previousCursor !== undefined ||
+            this.#disposed)
+            return this.#loadConversationFromGateway(input);
+        if (isGatewayDeadlineExceeded(input))
+            return {
+                ok: false,
+                error: createGatewayDeadlineExceededError(input.conversationId),
+            };
+        this.cancelPendingConversationLoad();
+        const ticket = this.#cacheRequestId;
+        const epoch = this.#cache.epochFor(input.conversationId);
+        this.#captureCache(input);
+        let entry = this.#cache.peek(input.conversationId);
+        let source = entry === undefined ? "none" : "memory";
+        if (entry === undefined && this.#cache.hasStorage) {
+            entry = await this.#cache.restore(input.conversationId, input);
+            if (entry !== undefined)
+                source = "storage";
+        }
+        if (this.#disposed ||
+            ticket !== this.#cacheRequestId ||
+            epoch !== this.#cache.epochFor(input.conversationId))
+            return runtimeFailure("conflict", "Cached load was superseded", input.conversationId);
+        this.#setCacheState({
+            conversationId: input.conversationId,
+            status: "syncing",
+            source,
+            freshness: entry === undefined
+                ? this.#cache.wasExpired(input.conversationId)
+                    ? "expired"
+                    : "miss"
+                : this.#cache.freshness(entry.savedAt),
+            ...(entry === undefined ? {} : { savedAt: entry.savedAt }),
+            unavailableAttachments: (entry?.unavailableAttachments ?? 0) +
+                (entry?.attachmentKeys?.length ?? 0),
+            storageError: this.#cache.storageError,
+        });
+        if (this.#disposed ||
+            ticket !== this.#cacheRequestId ||
+            epoch !== this.#cache.epochFor(input.conversationId))
+            return runtimeFailure("conflict", "Cached load was superseded", input.conversationId);
+        if (entry !== undefined &&
+            (this.getSnapshot()?.conversation.id !== input.conversationId ||
+                this.#cacheReadOnly)) {
+            const oldSubscription = this.#gatewaySubscription;
+            this.#gatewaySubscription = undefined;
+            this.#generation += 1;
+            this.#conversationEpoch += 1;
+            this.#historyRequestId += 1;
+            this.#cacheReadOnly = true;
+            this.#snapshotStore.commit(createSnapshotState(cachedDisplaySnapshot(entry.snapshot)));
+            void this.#runSubscriptionCleanup(() => oldSubscription?.dispose(input), input.conversationId);
+            if (ticket === this.#cacheRequestId &&
+                epoch === this.#cache.epochFor(input.conversationId))
+                this.#restoreCachedDraft(entry, source, input, ticket);
+        }
+        if (this.#disposed ||
+            ticket !== this.#cacheRequestId ||
+            epoch !== this.#cache.epochFor(input.conversationId))
+            return runtimeFailure("conflict", "Cached load was superseded", input.conversationId);
+        const result = await this.#loadConversationFromGateway(input);
+        if (this.#disposed ||
+            ticket !== this.#cacheRequestId ||
+            epoch !== this.#cache.epochFor(input.conversationId))
+            return result;
+        if (result.ok) {
+            this.#cacheReadOnly = false;
+            this.#captureCache(input);
+            this.#setCacheState({
+                ...this.#cacheState,
+                status: "ready",
+                freshness: "fresh",
+                savedAt: this.#cache.now(),
+                storageError: this.#cache.storageError,
+            });
+        }
+        else {
+            this.#setCacheState({
+                ...this.#cacheState,
+                status: "error",
+                storageError: this.#cache.storageError,
+            });
+            if (result.error.code === "not-found" ||
+                result.error.code === "authorization" ||
+                result.error.code === "authentication") {
+                await this.clearConversationCache(input.conversationId, input).catch(() => undefined);
+            }
+        }
+        return result;
+    }
+    #restoreCachedDraft(entry, source, input, ticket) {
+        const existing = this.#composerDrafts.get(input.conversationId);
+        if (existing !== undefined && existing.revision > 0)
+            return;
+        const draft = this.setComposerDraft({
+            conversationId: input.conversationId,
+            text: entry.draft.text,
+            longTexts: entry.draft.longTexts,
+            ...(source === "memory" ? { attachments: entry.draft.attachments } : {}),
+        });
+        if (source !== "storage")
+            return;
+        const epoch = this.#cache.epochFor(input.conversationId);
+        this.#setCacheState({
+            ...this.#cacheState,
+            unavailableAttachments: (entry.attachmentKeys?.length ?? 0) +
+                (entry.unavailableAttachments ?? 0),
+        });
+        void this.#cache.restoreAttachments(entry, input).then((restored) => {
+            if (this.#disposed ||
+                epoch !== this.#cache.epochFor(input.conversationId) ||
+                this.getComposerDraft(input.conversationId).revision !== draft.revision)
+                return;
+            const validated = sendMessageInputSchema.safeParse({
+                ...input,
+                text: draft.text || " ",
+                attachments: restored.attachments,
+            });
+            this.setComposerDraft({
+                conversationId: input.conversationId,
+                attachments: validated.success ? restored.attachments : [],
+            });
+            const unavailable = restored.unavailable +
+                (validated.success ? 0 : restored.attachments.length);
+            this.#cache.setUnavailableAttachments(input.conversationId, unavailable, input);
+            if (ticket === this.#cacheRequestId)
+                this.#setCacheState({
+                    ...this.#cacheState,
+                    unavailableAttachments: unavailable,
+                });
+        });
+    }
+    async #loadConversationFromGateway(input) {
         if (this.#disposed) {
             return runtimeFailure("conflict", "ChatClient has already been disposed", input.conversationId);
         }
@@ -261,7 +676,10 @@ export class ChatClient {
             await this.#discardGatewaySubscription(subscribed, input);
             return runtimeFailure("conflict", "Conversation load was superseded", input.conversationId);
         }
-        const loaded = await this.#gateway.loadConversation(input);
+        let loaded = await this.#gateway.loadConversation(input);
+        if (loaded.ok && loaded.value.conversation.id === input.conversationId) {
+            loaded = await this.#bridgeCachedHistory(input, loaded.value, requestId);
+        }
         if (!loaded.ok) {
             this.#clearPendingLoad(requestId);
             await this.#discardGatewaySubscription(subscribed, input);
@@ -310,9 +728,11 @@ export class ChatClient {
             this.#pendingLoadConversationId === input.conversationId
             ? this.#pendingLoadConversationOverride
             : undefined;
+        const cached = this.#cache?.peek(input.conversationId);
+        const loadedWithHistory = mergeCachedHistory(loaded.value, cached?.snapshot);
         const loadedState = createSnapshotState(conversationOverride === undefined
-            ? loaded.value
-            : { ...loaded.value, conversation: conversationOverride });
+            ? loadedWithHistory
+            : { ...loadedWithHistory, conversation: conversationOverride });
         const currentState = this.#snapshotStore.state;
         const handoff = this.#pendingHandoff;
         let nextState = handoff?.requestId === requestId && currentState !== null
@@ -327,6 +747,7 @@ export class ChatClient {
             nextState = this.#guardInteractionTransition(currentState, nextState);
         }
         this.#clearPendingLoad(requestId);
+        this.#cacheReadOnly = false;
         this.#snapshotStore.commit(nextState);
         if (!this.#disposed)
             notificationQueue.activate(generation);
@@ -347,6 +768,58 @@ export class ChatClient {
             this.#reportError(result.error, generation, "command");
         return result;
     }
+    async sendMessage(input) {
+        const parsed = sendMessageInputSchema.safeParse(input);
+        if (!parsed.success) {
+            return runtimeFailure("validation", "Message input is invalid", typeof input.conversationId === "string"
+                ? input.conversationId
+                : undefined);
+        }
+        const command = parsed.data;
+        const attachments = command.attachments ?? [];
+        if (attachments.length === 0) {
+            return this.sendText({
+                conversationId: command.conversationId,
+                deadlineAt: command.deadlineAt,
+                text: command.text ?? "",
+                ...(command.clientMessageId === undefined
+                    ? {}
+                    : { clientMessageId: command.clientMessageId }),
+            });
+        }
+        const state = this.#activeState(command.conversationId);
+        if (!state.ok)
+            return state;
+        if (!isGatewayOperationSupported(state.value.capabilities, "sendAttachments") ||
+            this.#gateway.sendMessage === undefined) {
+            return runtimeFailure("unsupported", "Attachment sending is unavailable", command.conversationId);
+        }
+        const inFlightKey = command.clientMessageId === undefined
+            ? undefined
+            : `${command.conversationId.length}:${command.conversationId}:${command.clientMessageId}`;
+        if (inFlightKey !== undefined) {
+            const existing = this.#messageSendsInFlight.get(inFlightKey);
+            if (existing !== undefined)
+                return existing;
+        }
+        const generation = this.#generation;
+        const operation = (async () => {
+            const result = await this.#gateway.sendMessage(command);
+            if (!result.ok && !this.#disposed)
+                this.#reportError(result.error, generation, "command");
+            return result;
+        })();
+        if (inFlightKey !== undefined) {
+            this.#messageSendsInFlight.set(inFlightKey, operation);
+            const clearInFlight = () => {
+                if (this.#messageSendsInFlight.get(inFlightKey) === operation) {
+                    this.#messageSendsInFlight.delete(inFlightKey);
+                }
+            };
+            void operation.then(clearInFlight, clearInFlight);
+        }
+        return operation;
+    }
     async answerInteraction(input) {
         const parsed = answerInteractionInputSchema.safeParse(input);
         if (!parsed.success) {
@@ -445,6 +918,10 @@ export class ChatClient {
     dispose(options) {
         if (this.#disposePromise !== undefined)
             return this.#disposePromise;
+        this.#captureCache(options);
+        const cacheClosed = this.#cache?.close();
+        this.#cacheListeners.clear();
+        this.#cacheRequestId += 1;
         this.#disposed = true;
         this.#conversationEpoch += 1;
         this.#generation += 1;
@@ -452,6 +929,10 @@ export class ChatClient {
         this.#interactionAnswersInFlight.clear();
         this.#retiredInteractionIdentities.clear();
         this.#supersededInteractionAnswers.clear();
+        this.#composerSendsInFlight.clear();
+        this.#messageSendsInFlight.clear();
+        this.#composerDrafts.clear();
+        this.#composerListeners.clear();
         this.#loadRequestId += 1;
         this.#pendingLoadConversationId = undefined;
         this.#pendingLoadConversationOverride = undefined;
@@ -461,6 +942,7 @@ export class ChatClient {
         const subscription = this.#gatewaySubscription;
         this.#gatewaySubscription = undefined;
         this.#disposePromise = Promise.allSettled([
+            cacheClosed,
             Promise.resolve().then(() => subscription?.dispose(options)),
             Promise.resolve().then(() => this.#gateway.dispose(options)),
         ]).then((results) => {
@@ -473,6 +955,42 @@ export class ChatClient {
         });
         return this.#disposePromise;
     }
+    async #bridgeCachedHistory(input, snapshot, requestId) {
+        const cached = this.#cache?.peek(input.conversationId);
+        if (cached === undefined || cached.snapshot.timeline.length === 0)
+            return { ok: true, value: snapshot };
+        const keys = new Set(cached.snapshot.timeline.map(getTimelineItemKey));
+        const cursors = new Set();
+        let current = snapshot;
+        while (current.pageInfo.hasPreviousPage &&
+            !current.timeline.some((item) => keys.has(getTimelineItemKey(item)))) {
+            const cursor = current.pageInfo.previousCursor;
+            if (this.#disposed || requestId !== this.#loadRequestId)
+                return runtimeFailure("conflict", "Cache synchronization was superseded", input.conversationId);
+            if (isGatewayDeadlineExceeded(input))
+                return {
+                    ok: false,
+                    error: createGatewayDeadlineExceededError(input.conversationId),
+                };
+            if (cursor === undefined || cursors.has(cursor) || cursors.size >= 50)
+                return runtimeFailure("conflict", "Cache synchronization could not establish continuous history", input.conversationId);
+            cursors.add(cursor);
+            const page = await this.#gateway.loadConversation({
+                ...input,
+                previousCursor: cursor,
+            });
+            if (!page.ok)
+                return page;
+            if (page.value.conversation.id !== input.conversationId)
+                return runtimeFailure("validation", "Gateway returned history for a different conversation", input.conversationId);
+            current = {
+                ...current,
+                timeline: mergeHistoryTimeline(createTimelineState(current.timeline), page.value.timeline).items,
+                pageInfo: page.value.pageInfo,
+            };
+        }
+        return { ok: true, value: current };
+    }
     async #loadHistory(input) {
         const active = this.#activeState(input.conversationId);
         if (!active.ok)
@@ -534,6 +1052,8 @@ export class ChatClient {
         if (this.#snapshotStore.state?.snapshot.conversation.id !== conversationId) {
             return runtimeFailure("conflict", "Conversation is not active in this ChatClient", conversationId);
         }
+        if (this.#cacheReadOnly)
+            return runtimeFailure("conflict", "Cached conversation is read-only until synchronization succeeds", conversationId);
         const lifecycle = this.#snapshotStore.state.snapshot.lifecycle;
         if (lifecycle !== undefined && !isChatLifecycleOperable(lifecycle)) {
             return runtimeFailure(lifecycle.status === "auth-required"
@@ -624,7 +1144,15 @@ export class ChatClient {
             return;
         }
         const state = this.#snapshotStore.latestState();
-        this.#snapshotStore.commit(this.#guardInteractionTransition(state, applySnapshotUpdate(state, update)));
+        const prepared = this.#cache !== undefined &&
+            update.kind === "snapshot.replace" &&
+            update.snapshot.conversation.id === state.snapshot.conversation.id
+            ? {
+                ...update,
+                snapshot: mergeCachedHistory(update.snapshot, state.snapshot),
+            }
+            : update;
+        this.#snapshotStore.commit(this.#guardInteractionTransition(state, applySnapshotUpdate(state, prepared)));
     }
     #guardInteractionTransition(current, candidate) {
         const currentInteraction = current.snapshot.pendingInteraction;