@vertesia/ui 1.5.0-dev.20260722.120446Z → 1.5.0-dev.20260725.083715Z

package/src/features/agent/chat/hooks/useAgentStream.test.tsx

@@ -124,6 +124,194 @@ describe('useAgentStream', () => {
         });
     });
 
+    it('retains structured update events even when their display message is empty', async () => {
+        const structuredUpdate: AgentMessage = {
+            ...createMessage(AgentMessageType.UPDATE, 1_000, ''),
+            details: { event_class: 'document_updated', document_id: 'document-1' },
+        };
+        const streamMessages = vi.fn<
+            (
+                id: string,
+                onMessage?: (message: AgentMessage, exitFn?: (payload: unknown) => void) => void,
+                since?: number,
+                signal?: AbortSignal,
+                options?: AgentRunStreamMessagesOptions,
+            ) => Promise<unknown>
+        >(async (_id, _onMessage, _since, _signal, options) => {
+            options?.onHistoryLoaded?.([structuredUpdate]);
+            return null;
+        });
+        const client = createClient(streamMessages);
+
+        const { result } = renderHook(() => useAgentStream(client, 'agent-run-1'));
+
+        await waitFor(() => {
+            expect(result.current.messages).toEqual([structuredUpdate]);
+        });
+    });
+
+    it('retains resource-bearing lifecycle messages loaded from history even when their text is empty', async () => {
+        const resourceMessage: AgentMessage = {
+            ...createMessage(AgentMessageType.THOUGHT, 1_000, ''),
+            details: {
+                event_class: 'activity',
+                tool: 'create_document',
+                tool_event: 'completed',
+                resources: [{ type: 'document', id: 'doc-1', label: 'Doc One', action: 'created' }],
+            },
+        };
+        const streamMessages = vi.fn<
+            (
+                id: string,
+                onMessage?: (message: AgentMessage, exitFn?: (payload: unknown) => void) => void,
+                since?: number,
+                signal?: AbortSignal,
+                options?: AgentRunStreamMessagesOptions,
+            ) => Promise<unknown>
+        >(async (_id, _onMessage, _since, _signal, options) => {
+            options?.onHistoryLoaded?.([resourceMessage]);
+            return null;
+        });
+        const client = createClient(streamMessages);
+
+        const { result } = renderHook(() => useAgentStream(client, 'agent-run-1'));
+
+        await waitFor(() => {
+            expect(result.current.messages).toEqual([resourceMessage]);
+        });
+    });
+
+    it('retains resource-bearing lifecycle messages received from the live stream', async () => {
+        let onStreamMessage: ((message: AgentMessage) => void) | undefined;
+        const streamMessages = vi.fn<
+            (
+                id: string,
+                onMessage?: (message: AgentMessage, exitFn?: (payload: unknown) => void) => void,
+                since?: number,
+                signal?: AbortSignal,
+            ) => Promise<unknown>
+        >(async (_id, onMessage) => {
+            onStreamMessage = onMessage;
+            return null;
+        });
+        const client = createClient(streamMessages);
+        const resourceMessage: AgentMessage = {
+            ...createMessage(AgentMessageType.THOUGHT, 1_000, ''),
+            details: {
+                event_class: 'activity',
+                tool: 'create_interaction',
+                tool_event: 'completed',
+                resources: [{ type: 'interaction', id: 'interaction-1', label: 'Daily News Agent', action: 'created' }],
+            },
+        };
+
+        const { result } = renderHook(() => useAgentStream(client, 'agent-run-1'));
+
+        await waitFor(() => {
+            expect(onStreamMessage).toBeDefined();
+        });
+
+        act(() => {
+            onStreamMessage?.(resourceMessage);
+        });
+
+        await waitFor(() => {
+            expect(result.current.messages).toEqual([resourceMessage]);
+        });
+    });
+
+    it('continues to discard empty housekeeping messages without resources', async () => {
+        const emptyThought = createMessage(AgentMessageType.THOUGHT, 1_000, '');
+        const streamMessages = vi.fn<
+            (
+                id: string,
+                onMessage?: (message: AgentMessage, exitFn?: (payload: unknown) => void) => void,
+                since?: number,
+                signal?: AbortSignal,
+                options?: AgentRunStreamMessagesOptions,
+            ) => Promise<unknown>
+        >(async (_id, onMessage, _since, _signal, options) => {
+            options?.onHistoryLoaded?.([emptyThought]);
+            onMessage?.(emptyThought);
+            return null;
+        });
+        const client = createClient(streamMessages);
+
+        const { result } = renderHook(() => useAgentStream(client, 'agent-run-1'));
+
+        await waitFor(() => {
+            expect(result.current.initialHistoryStatus).toBe('has_messages');
+        });
+        expect(result.current.messages).toEqual([]);
+    });
+
+    it('forwards delivered stream messages without reconnecting when the callback changes', async () => {
+        let deliver: ((message: AgentMessage) => void) | undefined;
+        const streamMessages = vi.fn<
+            (
+                id: string,
+                onMessage?: (message: AgentMessage, exitFn?: (payload: unknown) => void) => void,
+                since?: number,
+                signal?: AbortSignal,
+                options?: AgentRunStreamMessagesOptions,
+            ) => Promise<unknown>
+        >(async (_id, onMessage, _since, _signal, options) => {
+            deliver = onMessage;
+            options?.onHistoryLoaded?.([]);
+            return null;
+        });
+        const client = createClient(streamMessages);
+        const firstCallback = vi.fn();
+        const secondCallback = vi.fn();
+        const { rerender } = renderHook(
+            ({ onMessage }: { onMessage: (message: AgentMessage) => void }) =>
+                useAgentStream(client, 'agent-run-1', onMessage),
+            { initialProps: { onMessage: firstCallback } },
+        );
+
+        await waitFor(() => expect(deliver).toBeDefined());
+        act(() => deliver?.(createMessage(AgentMessageType.UPDATE, 1_000, 'first update')));
+        expect(firstCallback).toHaveBeenCalledTimes(1);
+
+        rerender({ onMessage: secondCallback });
+        act(() => deliver?.(createMessage(AgentMessageType.UPDATE, 1_100, 'second update')));
+
+        expect(firstCallback).toHaveBeenCalledTimes(1);
+        expect(secondCallback).toHaveBeenCalledTimes(1);
+        expect(streamMessages).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not forward replayed history deliveries to onMessage', async () => {
+        let deliver: ((message: AgentMessage) => void) | undefined;
+        const historical = createMessage(AgentMessageType.UPDATE, 1_000, 'historical update');
+        const streamMessages = vi.fn<
+            (
+                id: string,
+                onMessage?: (message: AgentMessage, exitFn?: (payload: unknown) => void) => void,
+                since?: number,
+                signal?: AbortSignal,
+                options?: AgentRunStreamMessagesOptions,
+            ) => Promise<unknown>
+        >(async (_id, onMessage, _since, _signal, options) => {
+            deliver = onMessage;
+            options?.onHistoryLoaded?.([historical]);
+            // Mirror completed-run behavior where archived events can be replayed
+            // immediately, before React has rendered the history state update.
+            onMessage?.(historical);
+            onMessage?.(createMessage(AgentMessageType.UPDATE, 900, 'older replay'));
+            return null;
+        });
+        const client = createClient(streamMessages);
+        const onMessage = vi.fn();
+        renderHook(() => useAgentStream(client, 'agent-run-1', onMessage));
+
+        await waitFor(() => expect(deliver).toBeDefined());
+        expect(onMessage).not.toHaveBeenCalled();
+
+        act(() => deliver?.(createMessage(AgentMessageType.UPDATE, 1_100, 'live update')));
+        expect(onMessage).toHaveBeenCalledTimes(1);
+    });
+
     it('marks initial history as errored when the history fetch fails', async () => {
         const streamMessages = vi.fn<
             (

package/src/features/agent/chat/hooks/useAgentStream.ts

@@ -5,6 +5,7 @@ import {
     AgentMessageType,
     type ConversationFile,
     type FileProcessingDetails,
+    getResourcesFromMessage,
 } from '@vertesia/common';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import {
@@ -98,12 +99,16 @@ function isTimelineStateMessage(message: AgentMessage): boolean {
 function shouldStoreTimelineMessage(message: AgentMessage): boolean {
     if (message.type === AgentMessageType.STREAMING_CHUNK) return false;
 
+    // Structured resource events must survive replay even if a producer accidentally
+    // omits the human-readable display message.
+    if (message.type === AgentMessageType.UPDATE && typeof message.details?.event_class === 'string') return true;
+
     if (message.type === AgentMessageType.SYSTEM) {
         const details = message.details as FileProcessingDetails | undefined;
         if (details?.system_type === 'file_processing' && details.files) return false;
     }
 
-    return Boolean(message.message) || isTimelineStateMessage(message);
+    return Boolean(message.message) || isTimelineStateMessage(message) || getResourcesFromMessage(message).length > 0;
 }
 
 function summarizeMessage(message: AgentMessage | undefined): Record<string, unknown> | undefined {
@@ -210,13 +215,19 @@ function getStreamingReplacementKeys(message: AgentMessage): string[] {
  * File-processing SYSTEM messages are passed through to the messages array
  * (Option A from the plan) so downstream hooks can react to them.
  */
-export function useAgentStream(client: VertesiaClient, agentRunId: string): UseAgentStreamResult {
+export function useAgentStream(
+    client: VertesiaClient,
+    agentRunId: string,
+    onMessage?: (message: AgentMessage) => void,
+): UseAgentStreamResult {
     const [messages, setMessages] = useState<AgentMessage[]>([]);
     const [isCompleted, setIsCompleted] = useState(false);
     const [initialHistoryStatus, setInitialHistoryStatus] =
         useState<UseAgentStreamResult['initialHistoryStatus']>('loading');
     const [agentRunStatus, setAgentRunStatus] = useState<string | null>(null);
     const [workflowRunId, setWorkflowRunId] = useState<string | null>(null);
+    const onMessageRef = useRef(onMessage);
+    onMessageRef.current = onMessage;
 
     // Server-side file processing status updates
     const [serverFileUpdates, setServerFileUpdates] = useState<Map<string, ConversationFile>>(new Map());
@@ -345,6 +356,12 @@ export function useAgentStream(client: VertesiaClient, agentRunId: string): UseA
                 agentRunId,
                 (message) => {
                     if (abortController.signal.aborted) return;
+                    // Completed and idle runs replay their archived history through the live
+                    // stream. Only forward genuinely new deliveries so onMessage consumers
+                    // never treat replayed events as fresh ones.
+                    if (!message.timestamp || message.timestamp > lastDeliveredTsRef.current) {
+                        onMessageRef.current?.(message);
+                    }
 
                     debugAgentChat('stream message', {
                         agentRunId,
@@ -450,6 +467,14 @@ export function useAgentStream(client: VertesiaClient, agentRunId: string): UseA
                     onHistoryLoaded: (historical) => {
                         if (abortController.signal.aborted) return;
                         const timelineMessages = historical.filter(shouldStoreTimelineMessage);
+                        // Advance the watermark synchronously before React processes the
+                        // history state update. Some completed streams replay history via
+                        // the live callback immediately after onHistoryLoaded returns.
+                        for (const message of historical) {
+                            if (message.timestamp && message.timestamp > lastDeliveredTsRef.current) {
+                                lastDeliveredTsRef.current = message.timestamp;
+                            }
+                        }
                         debugAgentChat('history loaded', {
                             agentRunId,
                             count: historical.length,
@@ -461,12 +486,7 @@ export function useAgentStream(client: VertesiaClient, agentRunId: string): UseA
                         setInitialHistoryStatus(historical.length > 0 ? 'has_messages' : 'empty');
                         if (timelineMessages.length > 0) {
                             setMessages((prev) =>
-                                timelineMessages.reduce((next, message) => {
-                                    if (message.timestamp && message.timestamp > lastDeliveredTsRef.current) {
-                                        lastDeliveredTsRef.current = message.timestamp;
-                                    }
-                                    return insertTimelineMessage(next, message);
-                                }, prev),
+                                timelineMessages.reduce((next, message) => insertTimelineMessage(next, message), prev),
                             );
                         }
                     },

package/src/features/agent/chat/index.ts

@@ -1,3 +1,13 @@
+// Resource deep-link resolver — lets an embedding app override how agent resource references
+// (documents, collections, interactions, ...) map to routes/links in the chat.
+export {
+    type AgentResourceLinkReference,
+    type AgentResourceResolver,
+    AgentResourceResolverProvider,
+    type AgentResourceTarget,
+    type ResourceResolveContext,
+    useAgentResourceResolver,
+} from '@vertesia/ui/widgets';
 export {
     AgentApprovalModeSelector,
     type AgentApprovalModeSelectorProps,
@@ -31,6 +41,7 @@ export * from './JumpingDots';
 export {
     ModernAgentConversation,
     type ModernAgentConversationProps,
+    type SendAgentMessageFn,
     type StartWorkflowFn,
     type StartWorkflowOptions,
 } from './ModernAgentConversation';

package/src/features/store/objects/DocumentSearchResults.tsx

@@ -23,7 +23,7 @@ import type { TypeRegistry } from '../types/TypeRegistry.js';
 import { useTypeRegistry } from '../types/TypeRegistryProvider.js';
 import { ContentDispositionButton } from './components/ContentDispositionButton';
 import { ContentOverview } from './components/ContentOverview';
-import { useDownloadFile } from './components/useDownloadFile';
+import { getContentObjectDownloadName, useDownloadFile } from './components/useDownloadFile';
 import { VectorSearchWidget } from './components/VectorSearchWidget';
 import { DocumentQuickFilterProvider } from './DocumentQuickFilter';
 import { DocumentTable } from './DocumentTable';
@@ -483,7 +483,7 @@ function OverviewDrawer({ object, onClose }: OverviewDrawerProps) {
                         variant="ghost"
                         size="sm"
                         title="Download"
-                        onClick={() => downloadFromContentSource(contentSource, object.name || object.content?.name)}
+                        onClick={() => downloadFromContentSource(contentSource, getContentObjectDownloadName(object))}
                     >
                         <Download className="size-4" />
                     </Button>