@nocobase/app-plugin-agents 1.0.0-beta.29 → 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,18 +25,83 @@ 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();
-    resumed = new Set();
-    resuming = new Map();
-    recoveryErrors = new Map();
+    recoveries = new Map();
     admissions = new Map();
     watches = new Map();
     messageVersions = new Map();
@@ -47,6 +115,8 @@ export class ChatController {
     disposed = false;
     generation = 0;
     detailVersions = new Map();
+    receiptVersions = new Map();
+    pendingReceipts = new Map();
     commandVersions = new Map();
     constructor(api) {
         this.api = api;
@@ -69,7 +139,22 @@ export class ChatController {
                     const admission = this.admissions.get(id);
                     if (!this.disposed && admission?.clientId === clientId)
                         admission.gate.resolve();
-                }, (options) => this.resendAccepted(id, options)),
+                }, (options) => this.resendAccepted(id, options), () => {
+                    const active = this.lifetime(), recovery = this.recoveries.get(id);
+                    return (available) => {
+                        if (!active() ||
+                            this.chats.get(id) !== chat ||
+                            !recovery ||
+                            this.recoveries.get(id) !== recovery)
+                            return;
+                        recovery.phase = available ? 'live' : 'history';
+                        recovery.error = undefined;
+                        // Reads started before reconnection must not replace its replay or revive old errors.
+                        this.nextDetailVersion(id);
+                        this.invalidateHistoryReads(id);
+                        this.publish();
+                    };
+                }),
                 onFinish: () => {
                     if (!this.disposed && this.chats.get(id) === chat)
                         this.scheduleRefresh(id);
@@ -180,15 +265,18 @@ export class ChatController {
         this.publish();
     }
     historyLifetime(id) {
-        const active = this.lifetime(), epoch = this.historyEpochs.get(id) ?? 0;
-        return () => active() && (this.historyEpochs.get(id) ?? 0) === epoch;
+        const active = this.lifetime(), epoch = this.historyEpochs.get(id) ?? 0, command = this.commandVersions.get(id);
+        return () => active() &&
+            (this.historyEpochs.get(id) ?? 0) === epoch &&
+            this.commandVersions.get(id) === command;
     }
-    invalidateHistoryReads(id) {
+    invalidateHistoryReads(id, discardDeferred = false) {
         this.historyEpochs.set(id, (this.historyEpochs.get(id) ?? 0) + 1);
         this.loads.delete(id);
         this.refreshAgain.delete(id);
         this.revisionQueue.delete(id);
-        this.deferredReads.delete(id);
+        if (discardDeferred)
+            this.deferredReads.delete(id);
         for (const key of this.messageVersions.keys())
             if (key.startsWith(`${id}:`))
                 this.messageVersions.delete(key);
@@ -221,8 +309,8 @@ export class ChatController {
         if (previous?.executionId === event.executionId ||
             (previous && previous.lastSeq > event.lastSeq))
             return false;
-        this.invalidateHistoryReads(id);
-        this.resuming.delete(id);
+        this.invalidateHistoryReads(id, true);
+        this.recoveries.delete(id);
         this.replacements.set(id, event);
         this.dispatch(id, { type: 'replaceHistory', ...event });
         this.historyMeta(id).loadedThrough = Math.max(this.historyMeta(id).loadedThrough, event.lastSeq);
@@ -391,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' &&
@@ -452,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,
@@ -547,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);
@@ -566,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) {
@@ -575,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);
@@ -594,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)) ||
@@ -617,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);
                 }
@@ -664,14 +833,16 @@ export class ChatController {
     async sendInput(id, input) {
         if (this.disposed)
             throw new CancelledError({ silent: true });
-        const chat = this.chat(id);
+        let chat = this.chat(id);
         if (chat.status === 'submitted' || chat.status === 'streaming')
             throw new Error('This conversation is already receiving a response.');
         if (this.resendRequests.has(id))
             throw new Error('This conversation is busy.');
         const admitted = deferred();
         this.admissions.set(id, { clientId: input.clientId, gate: admitted });
-        this.recoveryErrors.delete(id);
+        this.recoveries.delete(id);
+        // A new turn owns its callbacks, including when the previous transport finishes late.
+        chat = this.renewChat(id, chat.messages);
         const active = this.lifetime();
         const sending = chat.sendMessage({
             id: input.clientId,
@@ -697,6 +868,7 @@ export class ChatController {
         }, {
             body: {
                 ...(input.agentId ? { agentId: input.agentId } : {}),
+                ...(input.effort !== undefined ? { effort: input.effort } : {}),
                 ...(input.context ? { context: input.context } : {}),
                 ...(input.attachmentIds?.length
                     ? { attachmentIds: input.attachmentIds }
@@ -727,42 +899,98 @@ export class ChatController {
     }
     state(id) {
         const chat = this.chats.get(id);
+        const recovery = this.recoveries.get(id);
+        const recovering = recovery?.phase === 'recovering';
+        const error = recovering ? undefined : (chat?.error ?? recovery?.error);
         return chat
             ? {
                 status: chat.status,
-                error: chat.error ?? this.recoveryErrors.get(id),
+                error,
+                recovery: recovering
+                    ? 'recovering'
+                    : error
+                        ? 'interrupted'
+                        : recovery?.phase === 'history'
+                            ? 'history'
+                            : undefined,
             }
             : undefined;
     }
+    recoveryKey(id, detail) {
+        return (detail.run?.id ??
+            detail.execution?.messageId ??
+            (detail.execution?.status === 'running'
+                ? this.recoveries.get(id)?.key
+                : undefined) ??
+            [...this.chat(id).messages].reverse().find((m) => m.role === 'user')
+                ?.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 || this.resumed.has(id))
+        if (this.disposed)
             return;
         const detail = known ??
             agentsQueryClient().getQueryData(chatKeys.conversation(id));
-        if (!detail?.execution)
+        if (!detail ||
+            this.recoveries.get(id)?.key === this.recoveryKey(id, detail))
             return;
-        this.resumed.add(id);
-        if (detail?.execution?.status === 'idle' ||
-            detail?.execution?.waitingApproval)
-            return;
-        void this.resume(id);
+        void this.resume(id, detail);
     }
-    async resume(id) {
+    async resume(id, known) {
         if (this.disposed)
             return;
-        const pending = this.resuming.get(id);
-        if (pending)
-            return pending;
+        const detail = known ??
+            agentsQueryClient().getQueryData(chatKeys.conversation(id));
+        if (!detail)
+            return;
+        if (!chatIsRunning(detail) || detail.execution?.waitingApproval) {
+            const chat = this.chats.get(id);
+            if (chat?.status !== 'submitted' &&
+                chat?.status !== 'streaming' &&
+                (!this.history(id).state.loaded ||
+                    this.history(id).loadedThrough < (detail.lastSeq ?? 0)))
+                await this.loadHistory(id);
+            return;
+        }
+        const key = this.recoveryKey(id, detail);
+        const pending = this.recoveries.get(id);
         let chat = this.chat(id);
-        if (chat.status === 'submitted' || chat.status === 'streaming')
+        if (chat.status === 'submitted' || chat.status === 'streaming') {
+            if (!pending || pending.key !== key)
+                this.recoveries.set(id, { key, phase: 'live' });
             return;
+        }
+        if (pending?.key === key) {
+            if (pending.task)
+                return pending.task;
+            if (pending.phase === 'history')
+                return;
+        }
         const active = this.lifetime();
         const replacement = this.replacements.get(id);
-        const canResume = () => active() &&
+        const command = this.commandVersions.get(id);
+        const recovery = { key, phase: 'recovering' };
+        this.recoveries.set(id, recovery);
+        this.publish();
+        const current = () => active() &&
+            this.commandVersions.get(id) === command &&
+            this.recoveries.get(id) === recovery &&
             this.replacements.get(id) === replacement &&
-            this.chats.get(id) === chat &&
-            chat.status !== 'submitted' &&
-            chat.status !== 'streaming';
+            this.chats.get(id) === chat;
+        const canResume = () => current() && chat.status !== 'submitted' && chat.status !== 'streaming';
         const task = (async () => {
             let interrupted;
             try {
@@ -770,6 +998,8 @@ export class ChatController {
                 // A new input can begin while the recovery snapshot is still being read.
                 if (!canResume())
                     return;
+                if (this.history(id).error)
+                    throw this.history(id).error;
                 if (chat.error) {
                     const previous = chat;
                     interrupted = [...previous.messages]
@@ -790,36 +1020,63 @@ export class ChatController {
                     if (!active())
                         return;
                 }
-                this.recoveryErrors.delete(id);
                 chat.clearError();
                 const response = [...chat.messages]
                     .reverse()
                     .find((message) => message.role === 'assistant');
-                if (response)
+                if (response &&
+                    (response === interrupted ||
+                        !key ||
+                        response.metadata?.executionId === key ||
+                        response.id === detail.execution?.messageId)) {
+                    interrupted ??= response;
                     chat.messages = mergeUIMessages(chat.messages, [], response.id);
+                }
                 await chat.resumeStream();
-                if (active())
-                    await this.refresh(id);
+                if (current()) {
+                    if (chat.error) {
+                        recovery.phase = 'interrupted';
+                        recovery.error = chat.error;
+                    }
+                    if (agentsQueryClient()
+                        .getQueryCache()
+                        .find({ queryKey: chatKeys.conversation(id), exact: true })
+                        ?.isActive())
+                        this.scheduleRefresh(id);
+                    else
+                        await this.refresh(id);
+                }
             }
             catch (error) {
-                if (canResume())
-                    this.recoveryErrors.set(id, error instanceof Error
-                        ? error
-                        : new Error('Stream recovery failed.'));
+                if (current()) {
+                    if (chat.error) {
+                        recovery.phase = 'interrupted';
+                        recovery.error = chat.error;
+                    }
+                    else {
+                        // A failed history read is not evidence that the transport failed.
+                        this.historyMeta(id).error = error;
+                        if (recovery.phase === 'recovering')
+                            recovery.phase = 'live';
+                    }
+                }
             }
             finally {
-                if (active()) {
+                if (current()) {
                     const display = interrupted;
                     if (display &&
                         canResume() &&
                         !chat.messages.some((message) => message.id === display.id))
                         chat.messages = mergeUIMessages(chat.messages, [display]);
-                    this.resuming.delete(id);
+                    recovery.task = undefined;
+                    if (recovery.phase === 'recovering' &&
+                        (chat.status === 'submitted' || chat.status === 'streaming'))
+                        recovery.phase = 'live';
                     this.publish();
                 }
             }
         })();
-        this.resuming.set(id, task);
+        recovery.task = task;
         return task;
     }
     async approve(id, input) {
@@ -864,21 +1121,127 @@ 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)
+            ? [...submittedOwner.messages]
+                .reverse()
+                .find((message) => message.role === 'user' && message.metadata?.seq !== undefined)
+            : undefined;
+        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;
-        const active = this.lifetime(), ordered = this.detailRequest(id);
-        const detail = await this.api.conversation(id);
+        }
         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);
-        if (!active() || !ordered())
+        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);
         if (history.error)
@@ -892,25 +1255,49 @@ 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);
-        if (owner.status === 'streaming' &&
-            receiving?.role === 'assistant' &&
-            (detail.execution?.status === 'idle' ||
-                detail.execution?.waitingApproval) &&
-            saved.some((message) => message.id === receiving.id &&
+        const lastUser = [...owner.messages]
+            .reverse()
+            .find((message) => message.role === 'user');
+        const executionId = submittedInput?.metadata?.executionId ?? this.recoveries.get(id)?.key;
+        const submittedTerminal = owner === submittedOwner &&
+            owner.status === 'submitted' &&
+            submittedInput &&
+            lastUser?.id === submittedInput.id &&
+            detail.execution?.status === 'idle' &&
+            [...saved, ...owner.messages].some((message) => message.role !== 'user' &&
                 message.metadata?.seq !== undefined &&
-                message.metadata?.executionId === receiving.metadata?.executionId &&
-                message.metadata.revision >= (detail.execution?.revision ?? 0))) {
+                message.metadata.seq > submittedInput.metadata.seq &&
+                ((executionId && message.metadata.executionId === executionId) ||
+                    message.id === detail.execution?.messageId));
+        if (submittedTerminal ||
+            (owner.status === 'streaming' &&
+                receiving?.role === 'assistant' &&
+                (detail.execution?.status === 'idle' ||
+                    detail.execution?.waitingApproval) &&
+                saved.some((message) => message.id === receiving.id &&
+                    message.metadata?.seq !== undefined &&
+                    message.metadata?.executionId === receiving.metadata?.executionId &&
+                    message.metadata.revision >= (detail.execution?.revision ?? 0)))) {
             // Durable completion can release a lost subscriber; this never calls business Stop.
             await owner.stop();
             if (!active() || !ordered())
@@ -919,23 +1306,24 @@ export class ChatController {
         }
         if (!active() || !ordered())
             return;
-        this.remember(detail);
+        if (!snapshot)
+            this.remember(detail, false);
         const chat = this.chat(id);
         if (detail.execution?.status === 'idle') {
-            this.recoveryErrors.delete(id);
-            if (chat.error &&
-                saved.some((message) => message.id === chat.messages.at(-1)?.id &&
-                    message.metadata?.seq !== undefined))
+            this.recoveries.delete(id);
+            if (chat.error)
                 this.renewChat(id, chat.messages);
         }
-        else if (detail.execution?.status === 'running' &&
-            !detail.execution.waitingApproval &&
-            chat.status !== 'submitted' &&
-            chat.status !== 'streaming')
-            this.recoveryErrors.set(id, new Error('Execution remains active; reconcile saved history or resume its stream.'));
         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);
@@ -945,14 +1333,18 @@ export class ChatController {
                 void this.refresh(id).catch(() => { });
         });
     }
-    observeDetail(detail) {
+    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 (this.chats.get(detail.id)?.status === 'streaming')
-                this.scheduleRefresh(detail.id);
+            if (refresh &&
+                (this.chats.get(detail.id)?.status === 'streaming' ||
+                    this.chats.get(detail.id)?.status === 'submitted'))
+                void this.refreshOnce(detail.id, false, false, detail).catch(() => { });
             this.stopRequests.delete(detail.id);
-            this.recoveryErrors.delete(detail.id);
+            this.recoveries.delete(detail.id);
             this.publish();
         }
     }
@@ -987,16 +1379,112 @@ export class ChatController {
         const active = this.lifetime(), version = this.nextDetailVersion(id);
         return () => active() && this.detailVersions.get(id) === version;
     }
-    remember(detail) {
+    remember(detail, refresh = true) {
         this.nextDetailVersion(detail.id);
-        this.observeDetail(detail);
-        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);
+        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?.();
+            }
+        }
     }
     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);
+        if (recovery?.phase === 'history')
+            this.recoveries.set(id, { key: recovery.key, phase: 'history' });
+        else
+            this.recoveries.delete(id);
         await agentsQueryClient().cancelQueries({
             queryKey: chatKeys.conversation(id),
             exact: true,
@@ -1022,6 +1510,8 @@ export class ChatController {
         this.disposed = false;
     }
     invalidate() {
+        this.invalidations?.stop();
+        this.invalidations = undefined;
         if (this.disposed)
             return;
         this.disposed = true;
@@ -1036,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();
@@ -1045,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.resuming.clear();
-        this.resumed.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();
@@ -1071,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(() => {
@@ -1095,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) {