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

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

@@ -124,6 +124,251 @@ 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('does not apply replayed file_processing snapshots to server file updates', async () => {
+        let deliver: ((message: AgentMessage) => void) | undefined;
+        const fileSnapshot = (timestamp: number, id: string): AgentMessage => ({
+            timestamp,
+            workflow_run_id: 'run-1',
+            type: AgentMessageType.SYSTEM,
+            message: '',
+            workstream_id: 'main',
+            details: {
+                system_type: 'file_processing',
+                batch_id: 'batch-1',
+                files: [
+                    {
+                        id,
+                        name: `${id}.pdf`,
+                        content_type: 'application/pdf',
+                        size: 1,
+                        status: FileProcessingStatus.READY,
+                        artifact_path: `files/${id}.pdf`,
+                        reference: `artifact:files/${id}.pdf`,
+                        started_at: timestamp,
+                    },
+                ],
+                pending_count: 0,
+                ready_count: 1,
+                error_count: 0,
+            },
+        });
+        const historical = fileSnapshot(1_000, 'old-upload');
+        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]);
+            // Completed runs replay archived file_processing snapshots through the
+            // live callback; applying them would rehydrate every historical upload
+            // as a staged composer chip on reopen.
+            onMessage?.(historical);
+            return null;
+        });
+        const client = createClient(streamMessages);
+        const { result } = renderHook(() => useAgentStream(client, 'agent-run-1', vi.fn()));
+
+        await waitFor(() => expect(deliver).toBeDefined());
+        expect(result.current.serverFileUpdates.size).toBe(0);
+
+        act(() => deliver?.(fileSnapshot(1_100, 'new-upload')));
+        expect(result.current.serverFileUpdates.size).toBe(1);
+        expect(result.current.serverFileUpdates.has('new-upload')).toBe(true);
+    });
+
     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,15 @@ 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. Track replay status once, before the cursor advances below —
+                    // every replay-sensitive consumer in this callback must use it.
+                    const isReplay = Boolean(message.timestamp && message.timestamp <= lastDeliveredTsRef.current);
+                    // Only forward genuinely new deliveries so onMessage consumers
+                    // never treat replayed events as fresh ones.
+                    if (!isReplay) {
+                        onMessageRef.current?.(message);
+                    }
 
                     debugAgentChat('stream message', {
                         agentRunId,
@@ -409,7 +429,13 @@ export function useAgentStream(client: VertesiaClient, agentRunId: string): UseA
                     if (message.type === AgentMessageType.SYSTEM) {
                         const details = message.details as FileProcessingDetails | undefined;
                         if (details?.system_type === 'file_processing' && details.files) {
-                            setServerFileUpdates(new Map(details.files.map((file) => [file.id, file])));
+                            // Replayed snapshots list every file ever uploaded to the run as
+                            // READY; applying them on reconnect would rehydrate historical
+                            // uploads as staged composer chips. Only genuinely new updates
+                            // may touch the file state.
+                            if (!isReplay) {
+                                setServerFileUpdates(new Map(details.files.map((file) => [file.id, file])));
+                            }
                             return;
                         }
                         // Other SYSTEM messages fall through to normal handling
@@ -450,6 +476,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 +495,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,
@@ -29,8 +39,10 @@ export {
 } from './AskUserWidget';
 export * from './JumpingDots';
 export {
+    type AgentMessageFilter,
     ModernAgentConversation,
     type ModernAgentConversationProps,
+    type SendAgentMessageFn,
     type StartWorkflowFn,
     type StartWorkflowOptions,
 } from './ModernAgentConversation';

package/src/features/facets/PromptsFacetsNav.tsx

@@ -1,4 +1,4 @@
-import type { FacetBucket } from '@vertesia/common';
+import type { ComputedFacetResponse, FacetBucket } from '@vertesia/common';
 import {
     type Filter as BaseFilter,
     FilterBar,
@@ -11,11 +11,13 @@ import { useState } from 'react';
 import { filterValueToQueryValue, type SearchInterface, setSearchQueryValue } from './utils/SearchInterface';
 
 interface PromptsFacetsNavProps {
-    facets: {
-        role?: FacetBucket[];
-        status?: FacetBucket[];
-        tags?: FacetBucket[];
-    };
+    /**
+     * The facet response as the endpoint publishes it: `total` plus one entry per facet the caller
+     * asked for. The names are chosen per request, so the buckets are narrowed below rather than
+     * declared here — the previous `{ role, status, tags }` shape named facets this component never
+     * requests and could not describe a caller that asks for a different one.
+     */
+    facets: ComputedFacetResponse;
     search: SearchInterface;
     /**
      * Optional controlled filter state. When provided, the parent owns the filter list (and is
@@ -28,8 +30,14 @@ interface PromptsFacetsNavProps {
     filterGroups?: FilterGroup[];
 }
 
+function facetBuckets(facets: ComputedFacetResponse, name: string): FacetBucket[] {
+    const value = facets[name];
+    return Array.isArray(value) ? (value as FacetBucket[]) : [];
+}
+
 // Hook to create filter groups for prompts
 export function usePromptsFilterGroups(facets: PromptsFacetsNavProps['facets']): FilterGroup[] {
+    const roleBuckets = facetBuckets(facets, 'role');
     const customFilterGroups: FilterGroup[] = [];
 
     // Add name filter as text type
@@ -42,12 +50,12 @@ export function usePromptsFilterGroups(facets: PromptsFacetsNavProps['facets']):
     customFilterGroups.push(nameFilterGroup);
 
     // Add role filter as select type if role facets are available
-    if (facets.role && facets.role.length > 0) {
+    if (roleBuckets.length > 0) {
         const rolesFilterGroup = {
             name: 'role',
             placeholder: 'Role',
             type: 'select' as const,
-            options: facets.role.map((facet) => ({
+            options: roleBuckets.map((facet) => ({
                 label: facet._id,
                 value: facet._id,
                 count: facet.count,
@@ -62,7 +70,7 @@ export function usePromptsFilterGroups(facets: PromptsFacetsNavProps['facets']):
         placeholder: 'Tags',
         type: 'stringList' as const,
         multiple: true,
-        options: (facets.tags ?? []).map((facet) => ({
+        options: facetBuckets(facets, 'tags').map((facet) => ({
             label: facet._id,
             value: facet._id,
         })),

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>