Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
import type { ContentBlock, Msg, TextBlock } from '@agentscope-ai/agentscope/message';
import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
import { chatApi } from '@/api';
import type { ChatQueueItem } from '@/api/chat';
import { ApiError } from '@/api/client';
const QUEUE_REFRESH_INTERVAL_MS = 15_000;
const OPTIMISTIC_ITEM_PREFIX = 'optimistic:';
export interface ChatInputStartedValue {
queue_item_id?: string;
message_ids?: string[];
queue_item?: ChatQueueItem;
}
export interface ChatInputTerminalValue {
queue_item_id?: string;
message_ids?: string[];
message?: string;
}
/** Return every message carried by queue items in FIFO order. */
export const getQueueMessages = (items: ChatQueueItem[]): Msg[] =>
items.flatMap((item) => (Array.isArray(item.input) ? item.input : [item.input]));
/**
* Owns the editable pending-turn queue for one chat session.
*
* The hook keeps server snapshots, optimistic submissions, periodic repair
* polling, and queue mutations out of the reply-stream state machine.
*/
export function useChatQueue(
agentId: string | null,
sessionId: string | null,
onError: (error: Error) => void,
) {
const [items, setItems] = useState<ChatQueueItem[]>([]);
const [conversationMessageIds, setConversationMessageIds] = useState<Set<string>>(new Set());
const itemsRef = useRef<ChatQueueItem[]>([]);
const conversationMessageIdsRef = useRef<Set<string>>(new Set());
const snapshotVersionRef = useRef(0);
const refreshSequenceRef = useRef(0);
// Object identity distinguishes A -> B -> A from the original A visit.
const session = useMemo(() => ({ agentId, sessionId }), [agentId, sessionId]);
const activeSessionRef = useRef<typeof session | null>(null);
useLayoutEffect(() => {
activeSessionRef.current = session;
return () => {
activeSessionRef.current = null;
};
}, [session]);
const updateItems = useCallback((next: ChatQueueItem[]) => {
snapshotVersionRef.current += 1;
itemsRef.current = next;
setItems(next);
}, []);
const updateConversationMessageIds = useCallback((update: (ids: Set<string>) => void) => {
const next = new Set(conversationMessageIdsRef.current);
update(next);
conversationMessageIdsRef.current = next;
setConversationMessageIds(next);
}, []);
const reset = useCallback(() => {
updateItems([]);
updateConversationMessageIds((ids) => ids.clear());
}, [updateConversationMessageIds, updateItems]);
/** Apply an authoritative snapshot without erasing unaccepted local turns. */
const applyQueueSnapshot = useCallback(
(serverItems: ChatQueueItem[]) => {
const optimisticItems = itemsRef.current.filter((item) =>
item.id.startsWith(OPTIMISTIC_ITEM_PREFIX),
);
const serverMessageIds = new Set(
getQueueMessages(serverItems).map((message) => message.id),
);
const unmatchedOptimisticItems = optimisticItems.filter(
(item) =>
!getQueueMessages([item]).some((message) => serverMessageIds.has(message.id)),
);
updateItems([...serverItems, ...unmatchedOptimisticItems]);
},
[updateItems],
);
const refreshQueue = useCallback(async () => {
if (!agentId || !sessionId || activeSessionRef.current !== session) return;
const requestId = ++refreshSequenceRef.current;
const snapshotVersion = snapshotVersionRef.current;
try {
const response = await chatApi.queue(agentId, sessionId, true);
if (
activeSessionRef.current !== session ||
requestId !== refreshSequenceRef.current ||
snapshotVersion !== snapshotVersionRef.current
) {
return;
}
applyQueueSnapshot(response.items);
} catch {
// Focus, reconnect, or the next interval retries transient failures.
}
}, [agentId, sessionId, session, applyQueueSnapshot]);
const applyMutationSnapshot = useCallback(
(serverItems: ChatQueueItem[], snapshotVersion: number) => {
if (activeSessionRef.current !== session) return;
if (snapshotVersion !== snapshotVersionRef.current) {
// An SSE event or another response already changed the queue.
// Fetch current state instead of resurrecting an older snapshot.
void refreshQueue();
return;
}
applyQueueSnapshot(serverItems);
},
[session, applyQueueSnapshot, refreshQueue],
);
useEffect(() => {
reset();
if (!agentId || !sessionId) return;
void refreshQueue();
const refreshTimer = window.setInterval(
() => void refreshQueue(),
QUEUE_REFRESH_INTERVAL_MS,
);
const refreshOnFocus = () => void refreshQueue();
window.addEventListener('focus', refreshOnFocus);
window.addEventListener('online', refreshOnFocus);
return () => {
window.clearInterval(refreshTimer);
window.removeEventListener('focus', refreshOnFocus);
window.removeEventListener('online', refreshOnFocus);
};
}, [agentId, sessionId, refreshQueue, reset]);
const addOptimistic = useCallback(
(message: Msg, shownInConversation: boolean): string => {
const optimisticId = `${OPTIMISTIC_ITEM_PREFIX}${crypto.randomUUID()}`;
if (shownInConversation) {
updateConversationMessageIds((ids) => ids.add(message.id));
}
updateItems([
...itemsRef.current,
{
id: optimisticId,
created_at: message.created_at,
input: message,
state: 'queued',
error: null,
},
]);
return optimisticId;
},
[updateConversationMessageIds, updateItems],
);
const acceptOptimistic = useCallback(
(optimisticId: string, queueItemId: string | null) => {
if (!queueItemId) return;
updateItems(
itemsRef.current.map((item) =>
item.id === optimisticId ? { ...item, id: queueItemId } : item,
),
);
},
[updateItems],
);
const rollbackOptimistic = useCallback(
(optimisticId: string, messageId: string) => {
updateItems(itemsRef.current.filter((item) => item.id !== optimisticId));
updateConversationMessageIds((ids) => ids.delete(messageId));
},
[updateConversationMessageIds, updateItems],
);
/** Remove a started item and return the message payload for conversation UI. */
const startItem = useCallback(
(value: ChatInputStartedValue): ChatQueueItem | undefined => {
const startedIds = new Set(value.message_ids ?? []);
updateConversationMessageIds((ids) => {
for (const messageId of startedIds) ids.delete(messageId);
});
const localItem = itemsRef.current.find(
(item) =>
item.id === value.queue_item_id ||
(item.id.startsWith(OPTIMISTIC_ITEM_PREFIX) &&
getQueueMessages([item]).some((message) => startedIds.has(message.id))),
);
updateItems(
itemsRef.current.filter(
(item) =>
item.id !== value.queue_item_id &&
!(
item.id.startsWith(OPTIMISTIC_ITEM_PREFIX) &&
getQueueMessages([item]).some((message) => startedIds.has(message.id))
),
),
);
return value.queue_item ?? localItem;
},
[updateConversationMessageIds, updateItems],
);
const finishItem = useCallback(
(value: ChatInputTerminalValue) => {
const terminalIds = new Set(value.message_ids ?? []);
updateItems(
itemsRef.current.filter(
(item) =>
item.id !== value.queue_item_id &&
!getQueueMessages([item]).some((message) => terminalIds.has(message.id)),
),
);
updateConversationMessageIds((ids) => {
for (const messageId of terminalIds) ids.delete(messageId);
});
},
[updateConversationMessageIds, updateItems],
);
const updateQueued = useCallback(
async (itemId: string, text: string) => {
if (!agentId || !sessionId || activeSessionRef.current !== session) return;
const item = itemsRef.current.find((candidate) => candidate.id === itemId);
if (!item || Array.isArray(item.input)) return;
let replacedText = false;
const content: ContentBlock[] = [];
for (const block of item.input.content) {
if (block.type !== 'text') {
content.push(block);
} else if (!replacedText) {
replacedText = true;
content.push({ ...block, text });
}
}
if (!replacedText) {
const now = new Date().toISOString();
const textBlock: TextBlock = {
id: crypto.randomUUID(),
type: 'text',
text,
created_at: now,
finished_at: now,
};
content.unshift(textBlock);
}
const snapshotVersion = snapshotVersionRef.current;
try {
const response = await chatApi.updateQueued(itemId, {
agent_id: agentId,
session_id: sessionId,
input: { ...item.input, content },
});
applyMutationSnapshot(response.items, snapshotVersion);
} catch (error) {
if (activeSessionRef.current === session) onError(error as Error);
throw error;
}
},
[agentId, sessionId, session, applyMutationSnapshot, onError],
);
const deleteQueued = useCallback(
async (itemId: string) => {
if (!agentId || !sessionId || activeSessionRef.current !== session) return;
const snapshotVersion = snapshotVersionRef.current;
try {
const response = await chatApi.deleteQueued(itemId, agentId, sessionId);
applyMutationSnapshot(response.items, snapshotVersion);
} catch (error) {
if (activeSessionRef.current === session) onError(error as Error);
throw error;
}
},
[agentId, sessionId, session, applyMutationSnapshot, onError],
);
const steerQueued = useCallback(
async (itemId: string, replyId: string) => {
if (!agentId || !sessionId || activeSessionRef.current !== session) return;
const previousItem = itemsRef.current.find((item) => item.id === itemId);
if (!previousItem) return;
updateItems(
itemsRef.current.map((item) =>
item.id === itemId
? { ...item, state: 'steering' as const, error: null }
: item,
),
);
const snapshotVersion = snapshotVersionRef.current;
try {
const response = await chatApi.steerQueued(itemId, agentId, sessionId, replyId);
applyMutationSnapshot(response.items, snapshotVersion);
} catch (error) {
if (activeSessionRef.current === session) {
if (snapshotVersion === snapshotVersionRef.current) {
updateItems(
itemsRef.current.map((item) =>
item.id === itemId ? previousItem : item,
),
);
}
void refreshQueue();
onError(error as Error);
}
throw error;
}
},
[agentId, sessionId, session, applyMutationSnapshot, onError, updateItems, refreshQueue],
);
const reorderQueued = useCallback(
async (visibleItemIds: string[]) => {
if (!agentId || !sessionId || activeSessionRef.current !== session) return;
const current = itemsRef.current;
if (current.some((item) => item.id.startsWith(OPTIMISTIC_ITEM_PREFIX))) return;
const visibleIds = current
.filter(
(item) =>
!getQueueMessages([item]).some((message) =>
conversationMessageIdsRef.current.has(message.id),
),
)
.map((item) => item.id);
const visibleIdSet = new Set(visibleIds);
if (
visibleItemIds.length !== visibleIds.length ||
new Set(visibleItemIds).size !== visibleIds.length ||
visibleItemIds.some((itemId) => !visibleIdSet.has(itemId))
) {
return;
}
let visibleIndex = 0;
const fullItemIds = current.map((item) =>
visibleIdSet.has(item.id) ? visibleItemIds[visibleIndex++] : item.id,
);
const snapshotVersion = snapshotVersionRef.current;
try {
const response = await chatApi.reorderQueued(agentId, sessionId, fullItemIds);
applyMutationSnapshot(response.items, snapshotVersion);
} catch (error) {
if (activeSessionRef.current === session) {
onError(error as Error);
if (error instanceof ApiError && error.status === 409) {
await refreshQueue();
}
}
throw error;
}
},
[agentId, sessionId, session, applyMutationSnapshot, onError, refreshQueue],
);
const moveQueued = useCallback(
async (itemId: string, direction: -1 | 1) => {
const current = itemsRef.current.filter(
(item) =>
!getQueueMessages([item]).some((message) =>
conversationMessageIdsRef.current.has(message.id),
),
);
const index = current.findIndex((item) => item.id === itemId);
const nextIndex = index + direction;
if (index < 0 || nextIndex < 0 || nextIndex >= current.length) return;
const reordered = [...current];
[reordered[index], reordered[nextIndex]] = [reordered[nextIndex], reordered[index]];
await reorderQueued(reordered.map((item) => item.id));
},
[reorderQueued],
);
const visibleItems = useMemo(
() =>
items.filter(
(item) =>
!getQueueMessages([item]).some((message) =>
conversationMessageIds.has(message.id),
),
),
[conversationMessageIds, items],
);
const reorderDisabled = useMemo(
() =>
items.some(
(item) => item.id.startsWith(OPTIMISTIC_ITEM_PREFIX) || item.state === 'steering',
),
[items],
);
return {
items: visibleItems,
visibleCount: visibleItems.filter((item) => item.state !== 'steering').length,
pendingCount: items.length,
reorderDisabled,
addOptimistic,
acceptOptimistic,
rollbackOptimistic,
applyQueueSnapshot,
startItem,
finishItem,
updateQueued,
deleteQueued,
steerQueued,
moveQueued,
reorderQueued,
};
}