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

package/src/features/agent/chat/ModernAgentOutput/resourceSummary.ts

@@ -0,0 +1,152 @@
+import {
+    type AgentMessage,
+    AgentMessageType,
+    type AgentResourceReference,
+    getResourcesFromMessage,
+} from '@vertesia/common';
+import { getWorkstreamId, isInProgress } from './utils';
+
+interface ResourceAccumulator {
+    ref: AgentResourceReference;
+    /** The first action observed for this resource in the turn — indicates whether it pre-existed. */
+    firstAction: AgentResourceReference['action'];
+    /** The most recent action observed, in message order. */
+    lastAction: AgentResourceReference['action'];
+    /** True once a `created` action was seen for this resource within the turn. */
+    createdInTurn: boolean;
+}
+
+/**
+ * Dedupe the resources referenced across a set of messages by (type, id), modeling operations
+ * sequentially (in message order):
+ * - first created then finally deleted (create → … → delete) → transient scratch work that never
+ *   existed before the turn, omitted;
+ * - a resource that pre-existed (first action was delete/update) and ends deleted → kept as `deleted`
+ *   (e.g. delete → create → delete reports `deleted`, not transient);
+ * - any sequence ending in create, or containing a create when not ending deleted → kept as `created`;
+ * - otherwise `updated`.
+ * The most recently seen label/revision is retained, and first-mention order is preserved.
+ */
+function dedupeResources(messages: AgentMessage[]): AgentResourceReference[] {
+    const order: string[] = [];
+    const byKey = new Map<string, ResourceAccumulator>();
+
+    for (const message of messages) {
+        for (const ref of getResourcesFromMessage(message)) {
+            const key = `${ref.type}:${ref.id}`;
+            let entry = byKey.get(key);
+            if (!entry) {
+                entry = { ref, firstAction: ref.action, lastAction: ref.action, createdInTurn: false };
+                byKey.set(key, entry);
+                order.push(key);
+            }
+            entry.ref = ref;
+            entry.lastAction = ref.action;
+            if (ref.action === 'created') entry.createdInTurn = true;
+        }
+    }
+
+    const result: AgentResourceReference[] = [];
+    for (const key of order) {
+        const entry = byKey.get(key);
+        if (!entry) continue;
+        // Created first and ultimately deleted → never existed before the turn, transient: omit.
+        if (entry.firstAction === 'created' && entry.lastAction === 'deleted') continue;
+        const action: AgentResourceReference['action'] =
+            entry.lastAction === 'deleted'
+                ? 'deleted'
+                : entry.lastAction === 'created' || entry.createdInTurn
+                  ? 'created'
+                  : 'updated';
+        result.push({ ...entry.ref, action });
+    }
+    return result;
+}
+
+/**
+ * Split the conversation into turns at user QUESTION boundaries and return the deduped resources for
+ * each turn, in order. A turn spans from one user message up to (but excluding) the next. Turns with
+ * no resources still produce an entry (empty list) so callers can align positions with turn indices.
+ */
+export function segmentTurnResources(messages: AgentMessage[]): AgentResourceReference[][] {
+    if (messages.length === 0) return [];
+    const turns: AgentMessage[][] = [];
+    let current: AgentMessage[] = [];
+    let currentHasQuestion = false;
+    for (const message of messages) {
+        // Start a new turn at each user QUESTION, but fold any leading non-question messages (e.g. an
+        // initial system prompt) into the first turn so turn indices align with QUESTION order.
+        if (message.type === AgentMessageType.QUESTION && currentHasQuestion) {
+            turns.push(current);
+            current = [];
+            currentHasQuestion = false;
+        }
+        if (message.type === AgentMessageType.QUESTION) currentHasQuestion = true;
+        current.push(message);
+    }
+    if (current.length > 0) turns.push(current);
+
+    return turns.map(dedupeResources);
+}
+
+/**
+ * Aggregate the resources created/updated/deleted during the most recent turn. Convenience wrapper
+ * over {@link segmentTurnResources} for callers that only need the latest turn.
+ */
+export function aggregateLatestTurnResources(messages: AgentMessage[]): AgentResourceReference[] {
+    const turns = segmentTurnResources(messages);
+    return turns.length > 0 ? turns[turns.length - 1] : [];
+}
+
+/**
+ * Whether the latest main-workstream turn has produced its final response and its resource summary
+ * can be shown. Interactive conversations commonly remain alive after an ANSWER so they can accept
+ * another user message; requiring the entire workflow to become terminal would hide the summary for
+ * those otherwise-complete turns.
+ */
+export function isResourceSummaryReady(messages: AgentMessage[]): boolean {
+    if (!isInProgress(messages)) return true;
+
+    const mainMessages = messages.filter((message) => getWorkstreamId(message) === 'main');
+    const lastMainMessage = mainMessages[mainMessages.length - 1];
+    return lastMainMessage?.type === AgentMessageType.ANSWER;
+}
+
+export interface ResourceSummaryRenderItem {
+    type: 'resource_summary';
+    key: string;
+    resources: AgentResourceReference[];
+}
+
+/**
+ * Interleave per-turn resource summaries into a rendered timeline of `items`. A completed turn's
+ * summary is emitted right before the next turn begins, and the most recent completed turn's summary
+ * at the end. `isTurnBoundary` identifies the user-message item that starts a new turn; the i-th
+ * boundary maps to `turnResources[i - 1]`. The final (most recent) turn is only summarized when
+ * `isLatestTurnComplete` is true, so an in-progress turn shows no summary. Empty turns are skipped.
+ */
+export function interleaveTurnSummaries<T>(
+    items: T[],
+    isTurnBoundary: (item: T) => boolean,
+    turnResources: AgentResourceReference[][],
+    isLatestTurnComplete: boolean,
+): Array<T | ResourceSummaryRenderItem> {
+    if (turnResources.length === 0) return items;
+    const out: Array<T | ResourceSummaryRenderItem> = [];
+    const pushSummary = (turnIndex: number) => {
+        const resources = turnResources[turnIndex];
+        if (!resources || resources.length === 0) return;
+        const isLastTurn = turnIndex >= turnResources.length - 1;
+        if (isLastTurn && !isLatestTurnComplete) return;
+        out.push({ type: 'resource_summary', key: `resource-summary-${turnIndex}`, resources });
+    };
+    let boundariesSeen = 0;
+    for (const item of items) {
+        const boundary = isTurnBoundary(item);
+        if (boundary && boundariesSeen > 0) pushSummary(boundariesSeen - 1);
+        if (boundary) boundariesSeen += 1;
+        out.push(item);
+    }
+    pushSummary(boundariesSeen > 0 ? boundariesSeen - 1 : turnResources.length - 1);
+    return out;
+}

package/src/features/agent/chat/ModernAgentOutput/utils.test.ts

@@ -154,6 +154,23 @@ describe('ModernAgentOutput utils - progress state', () => {
 
         expect(isInProgress([idle, question])).toBe(true);
     });
+
+    it('ignores passive artifact working-copy saves after the agent goes idle', () => {
+        const idle = makeMessage({
+            timestamp: 1000,
+            type: AgentMessageType.IDLE,
+            message: 'Waiting for your command...',
+        });
+        const userAutosave = makeMessage({
+            timestamp: 2000,
+            type: AgentMessageType.UPDATE,
+            message: 'Updated working copy files/blog_post_draft.md',
+            details: { event_class: 'artifact_updated', source: 'user_edit', generation: '1784609448394436' },
+        });
+
+        // The user editing their artifact while the agent is idle must not resurrect "Working".
+        expect(isInProgress([idle, userAutosave])).toBe(false);
+    });
 });
 
 describe('ModernAgentOutput utils - sliding view thinking', () => {

package/src/features/agent/chat/ModernAgentOutput/utils.ts

@@ -55,6 +55,19 @@ export const DONE_STATES = [
     AgentMessageType.TERMINATED,
 ];
 
+/**
+ * Passive artifact working-copy saves (e.g. the user autosaving their edits in the collaborative
+ * editor) arrive as UPDATE messages with an `artifact_updated` event class. They are not agent
+ * activity: they must not flip the conversation back to "Working" and must not render as tool-call
+ * cards in the timeline.
+ */
+export function isPassiveArtifactUpdate(message: AgentMessage): boolean {
+    return (
+        message.type === AgentMessageType.UPDATE &&
+        (message.details as { event_class?: string } | undefined)?.event_class === 'artifact_updated'
+    );
+}
+
 export function isInProgress(messages: AgentMessage[]) {
     if (!messages.length) return true;
 
@@ -63,7 +76,7 @@ export function isInProgress(messages: AgentMessage[]) {
         message.details?._deliveryStatus === 'failed' &&
         DONE_STATES.includes(message.type);
 
-    const progressMessages = messages.filter((m) => !isTerminalOptimisticFailure(m));
+    const progressMessages = messages.filter((m) => !isTerminalOptimisticFailure(m) && !isPassiveArtifactUpdate(m));
 
     // Only the main workstream determines whether the conversation is in progress.
     // Child workstream COMPLETE/IDLE messages must not flip this flag.

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';