@nocobase/app-plugin-agents 2.0.0-beta.0 → 2.0.0-beta.1

package/dist/client/chat/controller.js

@@ -1,14 +1,17 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { ApiClientError } from '@nocobase/app-client';
-import { CancelledError } from '@tanstack/react-query';
+import { CancelledError, hashKey } from '@tanstack/react-query';
 import { isToolUIPart } from 'ai';
 import { Chat, useChat as useSDKChat } from '@ai-sdk/react';
 import { createContext, useContext, useEffect, useLayoutEffect, useMemo, useRef, useSyncExternalStore, } from 'react';
-import { useApiClient } from '@nocobase/app-client';
+import { useApiClient, useRealtimeReadiness } from '@nocobase/app-client';
+import { CONVERSATIONS_TOPIC, } from '../../shared/conversations.js';
 import { ChatApi } from './api.js';
+import { CHAT_INVALIDATION_MS, coalescedInvalidation, } from './coalesced-invalidation.js';
 import { chatIsRunning } from './feedback.js';
 import { ChatSubmissions } from './submissions.js';
 import { agentsQueryClient } from '../query.js';
+import { agentsKeys } from '../api/keys.js';
 import { chatKeys } from './keys.js';
 import { EMPTY_MESSAGES, messagesReducer, mergeUIMessages, } from './message-model.js';
 function deferred() {
@@ -22,14 +25,81 @@ function deferred() {
 /** Application coordination around one SDK Chat per conversation, shared by every surface. */
 export class ChatController {
     api;
+    invalidations;
+    invalidateQuery(key, exact = false) {
+        (this.invalidations ??= coalescedInvalidation(agentsQueryClient())).add(key, exact);
+    }
+    invalidateLists() {
+        for (const query of agentsQueryClient()
+            .getQueryCache()
+            .findAll({ queryKey: chatKeys.lists })) {
+            if (query.queryKey[3]?.archived !==
+                true)
+                this.invalidateQuery(query.queryKey, true);
+        }
+    }
+    /** Reuse a detail snapshot when replacing its row cannot change membership, order or a page cursor. */
+    syncLists(detail) {
+        const client = agentsQueryClient();
+        for (const query of client
+            .getQueryCache()
+            .findAll({ queryKey: chatKeys.lists })) {
+            const filter = query.queryKey[3];
+            if (filter?.archived === true)
+                continue;
+            const data = query.state.data;
+            const pageIndex = data?.pages?.findIndex((page) => page.items.some((item) => item.id === detail.id)) ?? -1;
+            const page = data?.pages?.[pageIndex];
+            const index = page?.items.findIndex((item) => item.id === detail.id) ?? -1;
+            const row = page?.items[index];
+            if (row &&
+                ((row.lastSeq ?? 0) > (detail.lastSeq ?? 0) ||
+                    row.updatedAt > detail.updatedAt))
+                continue;
+            const sameOrder = row &&
+                (row.lastMessageAt === detail.lastMessageAt ||
+                    (pageIndex === 0 &&
+                        index === 0 &&
+                        detail.lastMessageAt >= row.lastMessageAt &&
+                        (page.items.length > 1 || !page.nextCursor)));
+            if (!row ||
+                !sameOrder ||
+                query.state.fetchStatus !== 'idle' ||
+                row.archivedAt !== detail.archivedAt ||
+                row.showInChatList !== detail.showInChatList ||
+                filter?.q ||
+                filter?.agentId ||
+                filter?.mode ||
+                filter?.source ||
+                typeof filter === 'string') {
+                this.invalidateQuery(query.queryKey, true);
+                continue;
+            }
+            client.setQueryData(query.queryKey, {
+                ...data,
+                pages: data.pages.map((item, position) => position === pageIndex
+                    ? {
+                        ...item,
+                        items: item.items.map((summary) => summary.id === detail.id ? { ...detail } : summary),
+                    }
+                    : item),
+            });
+        }
+    }
     historyEpochs = new Map();
     replacements = new Map();
     resendRequests = new Map();
+    streamFollowers = new Map();
+    detailReads = new Map();
+    refreshes = new Map();
     reconciles = new Map();
     submissions;
     chats = new Map();
     histories = new Map();
     loads = new Map();
+    messageReads = new Map();
+    catchups = new Map();
+    reconnects = new Map();
     refreshAgain = new Set();
     recoveries = new Map();
     admissions = new Map();
@@ -46,6 +116,7 @@ export class ChatController {
     generation = 0;
     detailVersions = new Map();
     receiptVersions = new Map();
+    pendingReceipts = new Map();
     commandVersions = new Map();
     constructor(api) {
         this.api = api;
@@ -408,37 +479,31 @@ export class ChatController {
         const initial = this.chat(id).messages.filter((m) => m.metadata?.seq !== undefined);
         const task = (async () => {
             const found = [];
-            for (let offset = 0; offset < initial.length; offset += 100) {
-                const page = await this.api.messages(id, {
-                    ids: initial
-                        .slice(offset, offset + 100)
-                        .map((m) => m.id)
-                        .join(','),
-                });
+            // Reconnect reads the current window once, covering insertions, revisions and removed replies together.
+            const first = await this.api.messages(id, {});
+            if (!active())
+                return;
+            found.push(...first.items);
+            let window = first;
+            const oldest = Math.min(...initial.map((m) => m.metadata.seq));
+            const seen = new Set();
+            while (window.nextCursor &&
+                window.items.length &&
+                window.items[0].metadata.seq > oldest) {
+                if (seen.has(window.nextCursor))
+                    throw new Error('History pagination did not advance.');
+                seen.add(window.nextCursor);
+                window = await this.api.messages(id, { pageToken: window.nextCursor });
                 if (!active())
                     return;
-                found.push(...page.items);
+                found.push(...window.items);
             }
             const present = new Set(found.map((m) => m.id));
             const missing = new Set(initial.filter((m) => !present.has(m.id)).map((m) => m.id));
-            let window;
-            if (missing.size) {
-                const oldest = Math.min(...initial.map((m) => m.metadata.seq));
-                const seen = new Set();
-                do {
-                    window = await this.api.messages(id, window?.nextCursor ? { pageToken: window.nextCursor } : {});
-                    if (!active())
-                        return;
-                    found.push(...window.items);
-                    if (!window.nextCursor ||
-                        !window.items.length ||
-                        window.items[0].metadata.seq <= oldest)
-                        break;
-                    if (seen.has(window.nextCursor))
-                        throw new Error('History pagination did not advance.');
-                    seen.add(window.nextCursor);
-                } while (window.nextCursor);
-            }
+            this.dispatch(id, { type: 'page', page: first });
+            this.submissions.observe(id, found);
+            this.historyMeta(id).loadedThrough = first.lastSeq;
+            this.historyMeta(id).error = undefined;
             if (!active())
                 return;
             const changed = found.find((m) => m.role === 'user' &&
@@ -469,6 +534,13 @@ export class ChatController {
                 ? chat.messages.at(-1)?.id
                 : undefined;
             chat.messages = mergeUIMessages(chat.messages.filter((m) => !missing.has(m.id) || m.id === activeId), found, activeId);
+            const deferred = this.deferredReads.get(id);
+            for (const message of found)
+                if ((message.metadata?.revision ?? 0) >=
+                    (this.messageVersions.get(`${id}:${message.id}`) ?? 0))
+                    deferred?.delete(message.id);
+            if (deferred?.size === 0)
+                this.deferredReads.delete(id);
             if (window)
                 this.historyMeta(id).page = {
                     ...this.historyMeta(id).page,
@@ -564,9 +636,29 @@ export class ChatController {
         const found = [];
         const active = this.historyLifetime(id);
         for (let offset = 0; offset < ids.length; offset += 100) {
-            const page = await this.api.messages(id, {
-                ids: ids.slice(offset, offset + 100).join(','),
-            });
+            const selection = ids.slice(offset, offset + 100);
+            const key = JSON.stringify([id, [...selection].sort()]);
+            let pendingRead = this.messageReads.get(key);
+            const shared = Boolean(pendingRead);
+            if (!pendingRead) {
+                pendingRead = this.api.messages(id, { ids: selection.join(',') });
+                this.messageReads.set(key, pendingRead);
+                const clear = () => {
+                    if (this.messageReads.get(key) === pendingRead)
+                        this.messageReads.delete(key);
+                };
+                void pendingRead.then(clear, clear);
+            }
+            const page = await pendingRead;
+            if (shared &&
+                active() &&
+                page.items.some((message) => (message.metadata?.revision ?? 0) <
+                    (this.messageVersions.get(`${id}:${message.id}`) ?? 0))) {
+                // A revision announced during the older read needs a causal trailing read, never a cancellation.
+                const saved = await this.reread(id, selection);
+                found.push(...saved);
+                continue;
+            }
             if (!active())
                 return [];
             found.push(...page.items);
@@ -583,6 +675,42 @@ export class ChatController {
         }
         return found;
     }
+    /** A cursor announcement shares the current read; only an actual gap needs a trailing page. */
+    messagesChanged(id, lastSeq) {
+        if (this.disposed || !this.watches.has(id))
+            return Promise.resolve();
+        const pending = this.catchups.get(id);
+        if (pending) {
+            pending.lastSeq = Math.max(pending.lastSeq, lastSeq);
+            return pending.task;
+        }
+        const active = this.historyLifetime(id);
+        const owner = { lastSeq, task: Promise.resolve() };
+        const run = async () => {
+            const reading = this.loads.get(id);
+            if (reading)
+                await reading;
+            while (active() &&
+                (!this.history(id).state.loaded ||
+                    this.history(id).loadedThrough < owner.lastSeq)) {
+                const before = this.history(id).loadedThrough;
+                await this.loadHistory(id);
+                if (this.history(id).error)
+                    throw this.history(id).error;
+                if (this.history(id).loadedThrough <= before)
+                    break;
+            }
+        };
+        owner.task = run().finally(() => {
+            if (this.catchups.get(id) === owner)
+                this.catchups.delete(id);
+        });
+        this.catchups.set(id, owner);
+        return owner.task;
+    }
+    isWatching(id) {
+        return this.watches.has(id);
+    }
     watch(id) {
         let watch = this.watches.get(id);
         if (!watch) {
@@ -592,11 +720,15 @@ export class ChatController {
                     return;
                 const detail = agentsQueryClient().getQueryData(chatKeys.conversation(id));
                 const current = this.watches.get(id);
-                const interval = detail?.execution?.status === 'running' ? 5000 : 30000;
+                const status = this.chats.get(id)?.status;
+                const busy = chatIsRunning(detail ?? null) ||
+                    status === 'submitted' ||
+                    status === 'streaming';
+                const interval = busy ? 5000 : 30000;
                 if (Date.now() - current.last < interval)
                     return;
                 current.last = Date.now();
-                void this.refresh(id).catch(() => { });
+                void this.refresh(id, true, !busy, false).catch(() => { });
             }, 5000);
             watch = { refs: 0, timer, last: Date.now() };
             this.watches.set(id, watch);
@@ -611,12 +743,24 @@ export class ChatController {
         };
     }
     reconnect() {
-        for (const id of this.watches.keys())
-            void this.refresh(id)
+        this.invalidateLists();
+        for (const id of this.watches.keys()) {
+            if (this.reconnects.has(id))
+                continue;
+            const task = this.refresh(id)
                 .then(() => this.resume(id))
-                .catch(() => { });
+                .catch(() => { })
+                .finally(() => {
+                if (this.reconnects.get(id) === task)
+                    this.reconnects.delete(id);
+            });
+            this.reconnects.set(id, task);
+        }
     }
     messageUpdated(id, messageId, revision) {
+        const saved = this.chat(id).messages.find((message) => message.id === messageId);
+        if ((saved?.metadata?.revision ?? -1) >= revision)
+            return;
         const key = `${id}:${messageId}`;
         if (((this.messageVersions.get(key) ?? -1) >= revision &&
             !this.deferredReads.get(id)?.has(messageId)) ||
@@ -634,9 +778,17 @@ export class ChatController {
         queue.task = (async () => {
             const attempted = new Set();
             try {
+                // Let a concurrent cursor read or SDK finish supply the same durable revision first.
+                await new Promise((resolve) => setTimeout(resolve, CHAT_INVALIDATION_MS));
+                const reading = this.loads.get(id);
+                if (reading)
+                    await reading;
                 while (active() && queue.pending.size) {
-                    const ids = [...queue.pending];
+                    const ids = [...queue.pending].filter((messageId) => (this.chat(id).messages.find((message) => message.id === messageId)?.metadata?.revision ?? -1) <
+                        (this.messageVersions.get(`${id}:${messageId}`) ?? 0));
                     queue.pending.clear();
+                    if (!ids.length)
+                        continue;
                     ids.forEach((id) => attempted.add(id));
                     await this.reread(id, ids);
                 }
@@ -774,6 +926,19 @@ export class ChatController {
                 ?.id ??
             '');
     }
+    followStream(id) {
+        const count = (this.streamFollowers.get(id) ?? 0) + 1;
+        this.streamFollowers.set(id, count);
+        if (count === 1)
+            this.receive(id);
+        return () => {
+            const remaining = (this.streamFollowers.get(id) ?? 1) - 1;
+            if (remaining === 0)
+                this.streamFollowers.delete(id);
+            else
+                this.streamFollowers.set(id, remaining);
+        };
+    }
     receive(id, known) {
         if (this.disposed)
             return;
@@ -793,7 +958,10 @@ export class ChatController {
             return;
         if (!chatIsRunning(detail) || detail.execution?.waitingApproval) {
             const chat = this.chats.get(id);
-            if (chat?.status !== 'submitted' && chat?.status !== 'streaming')
+            if (chat?.status !== 'submitted' &&
+                chat?.status !== 'streaming' &&
+                (!this.history(id).state.loaded ||
+                    this.history(id).loadedThrough < (detail.lastSeq ?? 0)))
                 await this.loadHistory(id);
             return;
         }
@@ -870,7 +1038,13 @@ export class ChatController {
                         recovery.phase = 'interrupted';
                         recovery.error = chat.error;
                     }
-                    await this.refresh(id);
+                    if (agentsQueryClient()
+                        .getQueryCache()
+                        .find({ queryKey: chatKeys.conversation(id), exact: true })
+                        ?.isActive())
+                        this.scheduleRefresh(id);
+                    else
+                        await this.refresh(id);
                 }
             }
             catch (error) {
@@ -947,9 +1121,63 @@ export class ChatController {
         if (active())
             await this.refresh(id);
     }
-    async refresh(id) {
+    /** One detail request shared by the query observer and message reconciliation. */
+    readDetail(id, fresh = false) {
+        const pending = this.detailReads.get(id);
+        if (pending)
+            return fresh
+                ? pending.catch(() => undefined).then(() => this.readDetail(id))
+                : pending;
+        const task = this.api.conversation(id);
+        this.detailReads.set(id, task);
+        const clear = () => {
+            if (this.detailReads.get(id) === task)
+                this.detailReads.delete(id);
+        };
+        void task.then(clear, clear);
+        return task;
+    }
+    refresh(id, fresh = true, idleProbe = false, reconcileHistory = true) {
+        if (this.disposed)
+            return Promise.resolve();
+        const pending = this.refreshes.get(id);
+        if (pending) {
+            if (fresh) {
+                pending.trailing = true;
+                this.nextDetailVersion(id);
+            }
+            return pending.task;
+        }
+        const lifetime = this.lifetime(), commandVersion = this.commandVersions.get(id), active = () => lifetime() && this.commandVersions.get(id) === commandVersion;
+        const owner = { trailing: false, task: Promise.resolve() };
+        const run = async () => {
+            do {
+                owner.trailing = false;
+                await this.refreshOnce(id, fresh, idleProbe, undefined, reconcileHistory);
+                fresh = true;
+                idleProbe = false;
+            } while (owner.trailing && active());
+        };
+        owner.task = run().finally(() => {
+            if (this.refreshes.get(id) === owner)
+                this.refreshes.delete(id);
+        });
+        this.refreshes.set(id, owner);
+        return owner.task;
+    }
+    async refreshOnce(id, fresh, idleProbe = false, snapshot, reconcileHistory = true) {
         if (this.disposed)
             return;
+        const waiting = this.lifetime();
+        if ((!fresh || !reconcileHistory) && !snapshot) {
+            const query = agentsQueryClient()
+                .getQueryCache()
+                .find({ queryKey: chatKeys.conversation(id), exact: true });
+            if (query?.state.fetchStatus === 'fetching' && query.promise)
+                snapshot = (await query.promise);
+            if (!waiting())
+                return;
+        }
         const lifetime = this.lifetime(), commandVersion = this.commandVersions.get(id), active = () => lifetime() && this.commandVersions.get(id) === commandVersion, ordered = this.detailRequest(id);
         const submittedOwner = this.chat(id);
         const submittedInput = submittedOwner.status === 'submitted' && !this.admissions.has(id)
@@ -957,16 +1185,62 @@ export class ChatController {
                 .reverse()
                 .find((message) => message.role === 'user' && message.metadata?.seq !== undefined)
             : undefined;
-        const detail = await this.api.conversation(id);
+        const query = agentsQueryClient()
+            .getQueryCache()
+            .find({ queryKey: chatKeys.conversation(id), exact: true });
+        const cached = !fresh && query?.isActive() && query.state.fetchStatus === 'idle'
+            ? query.state.data
+            : undefined;
+        const previous = query?.state.data;
+        const detail = snapshot ?? cached ?? (await this.readDetail(id, fresh));
+        if (!active())
+            return;
+        if (idleProbe &&
+            previous &&
+            !chatIsRunning(detail) &&
+            detail.lastSeq !== undefined &&
+            this.history(id).state.loaded &&
+            !this.history(id).error &&
+            this.history(id).loadedThrough >= detail.lastSeq &&
+            hashKey([previous]) === hashKey([detail])) {
+            // The durable cursor is current. Still reread revisions of the latest assistant response: a same-sequence
+            // update may have lost its announcement, even though the conversation snapshot did not change.
+            const latest = [...this.chat(id).messages]
+                .reverse()
+                .find((message) => message.role === 'assistant');
+            const ids = [
+                ...new Set([
+                    ...(this.deferredReads.get(id) ?? []),
+                    ...(latest ? [latest.id] : []),
+                ]),
+            ];
+            if (ids.length)
+                await this.reread(id, ids);
+            if (active() && ordered()) {
+                this.remember(detail, false);
+                this.publish();
+            }
+            return;
+        }
         if (!active())
             return;
-        if (ordered())
+        const reconciled = fresh && !snapshot && reconcileHistory && ordered();
+        if (reconciled)
             await this.reconcile(id, detail);
         if (!active())
             return;
         // A newer detail query must not discard this refresh's message catch-up.
         // loadHistory coalesces overlapping reads independently of detail ordering.
-        await this.loadHistory(id, false, true);
+        const beforeThrough = this.history(id).loadedThrough;
+        if ((!snapshot && !reconciled && fresh && detail.lastSeq === undefined) ||
+            (reconciled && !ordered()) ||
+            !this.history(id).state.loaded ||
+            this.history(id).loadedThrough < (detail.lastSeq ?? 0)) {
+            if (!reconcileHistory && detail.lastSeq !== undefined)
+                await this.messagesChanged(id, detail.lastSeq);
+            else
+                await this.loadHistory(id, false, fresh);
+        }
         if (!active())
             return;
         const history = this.history(id);
@@ -981,14 +1255,23 @@ export class ChatController {
         const revisable = [
             ...new Set([
                 ...(this.deferredReads.get(id) ?? []),
-                ...(detail.execution?.messageId
+                ...(detail.execution?.messageId &&
+                    ((!snapshot &&
+                        !reconciled &&
+                        this.history(id).loadedThrough === beforeThrough) ||
+                        (this.chat(id).messages.find((m) => m.id === detail.execution?.messageId)?.metadata?.revision ?? -1) < (detail.execution.revision ?? 0))
                     ? [detail.execution.messageId]
-                    : latest
+                    : !snapshot &&
+                        !reconciled &&
+                        this.history(id).loadedThrough === beforeThrough &&
+                        latest
                         ? [latest.id]
                         : []),
             ]),
         ];
-        const saved = revisable.length ? await this.reread(id, revisable) : [];
+        const saved = revisable.length
+            ? await this.reread(id, revisable)
+            : [...this.chat(id).messages];
         if (!active() || !ordered())
             return;
         const owner = this.chat(id), receiving = owner.messages.at(-1);
@@ -1023,7 +1306,8 @@ export class ChatController {
         }
         if (!active() || !ordered())
             return;
-        this.remember(detail, false);
+        if (!snapshot)
+            this.remember(detail, false);
         const chat = this.chat(id);
         if (detail.execution?.status === 'idle') {
             this.recoveries.delete(id);
@@ -1033,6 +1317,13 @@ export class ChatController {
         this.publish();
     }
     scheduleRefresh(id) {
+        if (agentsQueryClient()
+            .getQueryCache()
+            .find({ queryKey: chatKeys.conversation(id), exact: true })
+            ?.isActive()) {
+            this.invalidateQuery(chatKeys.conversation(id), true);
+            return;
+        }
         if (this.completionReads.has(id))
             return;
         this.completionReads.add(id);
@@ -1042,14 +1333,16 @@ export class ChatController {
                 void this.refresh(id).catch(() => { });
         });
     }
-    observeDetail(detail, refresh = true) {
+    observeDetail(detail, refresh = true, synchronizeLists = true) {
+        if (synchronizeLists)
+            this.syncLists(detail);
         if (detail.execution?.status === 'running')
             this.receive(detail.id, detail);
         if (!chatIsRunning(detail)) {
             if (refresh &&
                 (this.chats.get(detail.id)?.status === 'streaming' ||
                     this.chats.get(detail.id)?.status === 'submitted'))
-                this.scheduleRefresh(detail.id);
+                void this.refreshOnce(detail.id, false, false, detail).catch(() => { });
             this.stopRequests.delete(detail.id);
             this.recoveries.delete(detail.id);
             this.publish();
@@ -1088,29 +1381,103 @@ export class ChatController {
     }
     remember(detail, refresh = true) {
         this.nextDetailVersion(detail.id);
-        this.observeDetail(detail, refresh);
-        agentsQueryClient().setQueryData(chatKeys.conversation(detail.id), detail);
-        void agentsQueryClient().invalidateQueries({ queryKey: chatKeys.lists });
+        // A reconnect already owns a fresh list read; its later history response must not schedule another one.
+        this.observeDetail(detail, refresh, !this.reconnects.has(detail.id));
+        const client = agentsQueryClient();
+        client.setQueryData(chatKeys.conversation(detail.id), detail);
+    }
+    /** The HTTP receipt supplies this tab's snapshot; retain a newer read position for a trailing read. */
+    observeReceipt(id, seenSeq) {
+        const update = (item) => {
+            if (item.id !== id || (item.seenSeq ?? -1) >= seenSeq)
+                return item;
+            return {
+                ...item,
+                seenSeq,
+                read: seenSeq >= (item.lastSeq ?? 0) || item.read,
+                needsYou: item.needsYou &&
+                    item.needsYou.reason !== 'confirm' &&
+                    item.needsYou.seq <= seenSeq
+                    ? null
+                    : item.needsYou,
+            };
+        };
+        agentsQueryClient().setQueriesData({ queryKey: chatKeys.lists }, (old) => !old
+            ? old
+            : Array.isArray(old)
+                ? old.map(update)
+                : {
+                    ...old,
+                    pages: old.pages.map((page) => ({
+                        ...page,
+                        items: page.items.map(update),
+                    })),
+                });
+    }
+    deferReadReceipt(id, seenSeq, refresh) {
+        const pending = this.pendingReceipts.get(id);
+        if (!pending)
+            return false;
+        pending.seenSeq = Math.max(pending.seenSeq, seenSeq);
+        pending.refresh = refresh;
+        return true;
     }
     async markRead(id) {
+        const client = agentsQueryClient();
+        const key = chatKeys.conversation(id);
+        const before = client.getQueryData(key);
         const active = this.lifetime(), commandVersion = this.commandVersions.get(id), receiptVersion = (this.receiptVersions.get(id) ?? 0) + 1;
         // Detail reads must not suppress the read transition needed by a viewed conversation.
         this.receiptVersions.set(id, receiptVersion);
+        const pending = { seenSeq: -1 };
+        this.pendingReceipts.set(id, pending);
         this.nextDetailVersion(id);
-        const detail = await this.api.markRead(id);
-        if (active() &&
-            this.commandVersions.get(id) === commandVersion &&
-            this.receiptVersions.get(id) === receiptVersion) {
-            // Read receipts do not change execution or invalidate pending history.
-            this.nextDetailVersion(id);
-            agentsQueryClient().setQueryData(chatKeys.conversation(id), detail);
-            void agentsQueryClient().invalidateQueries({ queryKey: chatKeys.lists });
+        try {
+            const detail = await this.api.markRead(id);
+            if (active() &&
+                this.commandVersions.get(id) === commandVersion &&
+                this.receiptVersions.get(id) === receiptVersion) {
+                this.observeReceipt(id, detail.seenSeq ?? 0);
+                // Read receipts do not change execution or invalidate pending history.
+                this.nextDetailVersion(id);
+                client.setQueryData(key, (current) => {
+                    if (!current ||
+                        current === before ||
+                        (current.lastSeq ?? 0) < (detail.lastSeq ?? 0) ||
+                        (current.lastSeq === detail.lastSeq &&
+                            current.updatedAt < detail.updatedAt))
+                        return detail;
+                    // A later snapshot may already contain the next reply or a metadata change.
+                    const seenSeq = Math.max(current.seenSeq ?? 0, detail.seenSeq ?? 0);
+                    return {
+                        ...current,
+                        seenSeq,
+                        read: seenSeq >= (current.lastSeq ?? 0) || current.read,
+                        needsYou: current.needsYou &&
+                            current.needsYou.reason !== 'confirm' &&
+                            current.needsYou.seq <= seenSeq
+                            ? null
+                            : current.needsYou,
+                    };
+                });
+            }
+            return detail;
+        }
+        finally {
+            if (this.pendingReceipts.get(id) === pending) {
+                this.pendingReceipts.delete(id);
+                const current = agentsQueryClient().getQueryData(chatKeys.conversation(id));
+                if (active() && pending.seenSeq > (current?.seenSeq ?? -1))
+                    pending.refresh?.();
+            }
         }
-        return detail;
     }
     async command(id, request, detail) {
         const active = this.lifetime(), version = (this.commandVersions.get(id) ?? 0) + 1;
         this.commandVersions.set(id, version);
+        // A command replaces the snapshot generation; its reads must not wait on obsolete HTTP.
+        this.detailReads.delete(id);
+        this.refreshes.delete(id);
         this.nextDetailVersion(id);
         this.invalidateHistoryReads(id);
         const recovery = this.recoveries.get(id);
@@ -1143,6 +1510,8 @@ export class ChatController {
         this.disposed = false;
     }
     invalidate() {
+        this.invalidations?.stop();
+        this.invalidations = undefined;
         if (this.disposed)
             return;
         this.disposed = true;
@@ -1157,6 +1526,9 @@ export class ChatController {
         this.historyEpochs.clear();
         this.replacements.clear();
         this.reconciles.clear();
+        this.streamFollowers.clear();
+        this.detailReads.clear();
+        this.refreshes.clear();
         for (const watch of this.watches.values())
             clearInterval(watch.timer);
         this.watches.clear();
@@ -1166,14 +1538,19 @@ export class ChatController {
         this.completionReads.clear();
         this.admissions.clear();
         this.loads.clear();
+        this.messageReads.clear();
+        this.catchups.clear();
+        this.reconnects.clear();
         this.refreshAgain.clear();
         this.commandVersions.clear();
         this.receiptVersions.clear();
+        this.pendingReceipts.clear();
         this.stopRequests.clear();
         this.approvalRequests.clear();
         this.recoveries.clear();
         this.submissions.invalidate();
-        agentsQueryClient().removeQueries({ queryKey: chatKeys.all });
+        // All plugin snapshots are viewer-scoped, including fresh agent options.
+        agentsQueryClient().removeQueries({ queryKey: agentsKeys.all });
     }
     dispose() {
         this.invalidate();
@@ -1192,10 +1569,7 @@ export function ChatClientProvider({ children, }) {
         controller.activate();
         const lifetimes = lifetimesRef.current;
         lifetimes.set(controller, (lifetimes.get(controller) ?? 0) + 1);
-        const reconnect = () => controller.reconnect();
-        window.addEventListener('online', reconnect);
         return () => {
-            window.removeEventListener('online', reconnect);
             controller.invalidate();
             lifetimes.set(controller, (lifetimes.get(controller) ?? 1) - 1);
             queueMicrotask(() => {
@@ -1216,12 +1590,13 @@ export function useChatController() {
 }
 export function useChatStream(id) {
     const controller = useChatController();
+    const ready = useRealtimeReadiness([CONVERSATIONS_TOPIC]);
     useSDKChat({ chat: controller.chat(id ?? 'draft') });
     useSyncExternalStore(controller.subscribe, controller.snapshot, controller.snapshot);
     useEffect(() => {
-        if (id)
-            controller.receive(id);
-    }, [controller, id]);
+        if (ready && id)
+            return controller.followStream(id);
+    }, [controller, id, ready]);
     return id ? controller.state(id) : undefined;
 }
 export function useChatStreamState(id) {