@vertesia/ui 1.4.0-dev.20260615.051508Z → 1.4.0

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

@@ -7,7 +7,12 @@ import {
     type FileProcessingDetails,
 } from '@vertesia/common';
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { insertMessageInTimeline, isInProgress } from '../ModernAgentOutput/utils';
+import {
+    debugAgentChat,
+    insertMessageInTimeline,
+    isInProgress,
+    isUserStoppedMessage,
+} from '../ModernAgentOutput/utils';
 
 /** Streaming data for a single active stream, keyed by streaming/activity ID */
 export interface StreamingData {
@@ -16,16 +21,24 @@ export interface StreamingData {
     isComplete?: boolean;
     startTimestamp: number;
     activityId?: string;
+    streamingId?: string;
 }
 
 export interface UseAgentStreamResult {
     messages: AgentMessage[];
     streamingMessages: Map<string, StreamingData>;
     isCompleted: boolean;
+    /** Initial history fetch state for deciding whether empty-run fallbacks are legitimate. */
+    initialHistoryStatus: 'loading' | 'empty' | 'has_messages' | 'error';
     /** Whether we are receiving chunks right now (for visual indicators) */
     debugChunkFlash: boolean;
     /** Add an optimistic message (for user input) */
     addOptimisticMessage: (msg: AgentMessage) => void;
+    /** Update optimistic delivery state for a client-generated message id */
+    updateOptimisticMessageStatus: (
+        messageId: string,
+        status: NonNullable<Common.AgentMessageDetails['_deliveryStatus']>,
+    ) => void;
     /** Remove optimistic messages matching a predicate */
     removeOptimisticMessages: (predicate: (msg: AgentMessage) => boolean) => void;
     /**
@@ -42,6 +55,146 @@ export interface UseAgentStreamResult {
     serverFileUpdates: Map<string, ConversationFile>;
 }
 
+function withDeliveryStatus(
+    message: AgentMessage,
+    status: NonNullable<Common.AgentMessageDetails['_deliveryStatus']>,
+): AgentMessage {
+    return {
+        ...message,
+        details: {
+            ...(message.details ?? {}),
+            _deliveryStatus: status,
+        },
+    };
+}
+
+function getClientMessageId(message: AgentMessage): string | undefined {
+    const details = message.details;
+    const messageId = details?._messageId;
+    if (typeof messageId === 'string' && messageId) return messageId;
+
+    const ack = details?.ack;
+    return typeof ack === 'string' && ack ? ack : undefined;
+}
+
+function getStringDetail(details: Common.AgentMessageDetails | undefined, key: string): string | undefined {
+    const value = details?.[key];
+    return typeof value === 'string' && value ? value : undefined;
+}
+
+function isWorkflowRunScopedStreamingId(details: Common.AgentMessageDetails | undefined): boolean {
+    return details?.streaming_id_scope === 'workflow_run';
+}
+
+function isTimelineStateMessage(message: AgentMessage): boolean {
+    return [
+        AgentMessageType.COMPLETE,
+        AgentMessageType.IDLE,
+        AgentMessageType.TERMINATED,
+        AgentMessageType.REQUEST_INPUT,
+    ].includes(message.type);
+}
+
+function shouldStoreTimelineMessage(message: AgentMessage): boolean {
+    if (message.type === AgentMessageType.STREAMING_CHUNK) return false;
+
+    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);
+}
+
+function summarizeMessage(message: AgentMessage | undefined): Record<string, unknown> | undefined {
+    if (!message) return undefined;
+    return {
+        type: message.type,
+        timestamp: message.timestamp,
+        workstream_id: message.workstream_id,
+        text:
+            typeof message.message === 'string' ? message.message.slice(0, 80) : message.message ? '[non-string]' : '',
+        display_role: message.details?.display_role,
+        source: message.details?.source,
+    };
+}
+
+function insertTimelineMessage(prev: AgentMessage[], message: AgentMessage): AgentMessage[] {
+    if (prev.find((m) => m.timestamp === message.timestamp)) {
+        return prev;
+    }
+
+    // For acked server messages, replace the matching optimistic version.
+    if (
+        !message.details?._optimistic &&
+        (message.type === AgentMessageType.QUESTION || isUserStoppedMessage(message))
+    ) {
+        const ack = typeof message.details?.ack === 'string' ? message.details.ack : undefined;
+        const consumedMessage = ack ? withDeliveryStatus(message, 'consumed') : message;
+
+        if (ack) {
+            const next = prev.filter(
+                (m) =>
+                    !(
+                        (m.type === message.type || isUserStoppedMessage(m)) &&
+                        m.details?._optimistic &&
+                        getClientMessageId(m) === ack
+                    ),
+            );
+            insertMessageInTimeline(next, consumedMessage);
+            return next;
+        }
+
+        if (message.type === AgentMessageType.QUESTION) {
+            // Legacy fallback for older workflow echoes that predate `details.ack`.
+            const matchingOptimistic = prev.filter(
+                (m) =>
+                    m.type === AgentMessageType.QUESTION &&
+                    m.details?._optimistic &&
+                    m.message === message.message &&
+                    (m.workstream_id ?? 'main') === (message.workstream_id ?? 'main'),
+            );
+            if (matchingOptimistic.length === 1) {
+                const next = prev.filter((m) => m !== matchingOptimistic[0]);
+                insertMessageInTimeline(next, message);
+                return next;
+            }
+        }
+    }
+
+    const next = [...prev];
+    insertMessageInTimeline(next, message);
+    return next;
+}
+
+function getStreamingChunkKey(message: AgentMessage): string | undefined {
+    const details = message.details;
+    const streamingId = getStringDetail(details, 'streaming_id');
+    const activityId = getStringDetail(details, 'activity_id');
+
+    if (streamingId && isWorkflowRunScopedStreamingId(details)) return streamingId;
+
+    // Backward compatibility: older compact chunks used workstream_id as
+    // streaming_id, so activity_id is the more specific key when present.
+    return activityId ?? streamingId;
+}
+
+function getStreamingReplacementKeys(message: AgentMessage): string[] {
+    const details = message.details;
+    const streamingId = getStringDetail(details, 'streaming_id');
+    const activityId = getStringDetail(details, 'activity_id');
+    const keys: string[] = [];
+
+    if (streamingId && isWorkflowRunScopedStreamingId(details)) {
+        keys.push(streamingId);
+    }
+    if (activityId) {
+        keys.push(activityId);
+    }
+
+    return [...new Set(keys)];
+}
+
 /**
  * Hook that manages the SSE message stream for an agent conversation.
  *
@@ -60,6 +213,8 @@ export interface UseAgentStreamResult {
 export function useAgentStream(client: VertesiaClient, agentRunId: string): 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);
 
@@ -118,6 +273,19 @@ export function useAgentStream(client: VertesiaClient, agentRunId: string): UseA
         setIsCompleted(!isInProgress(messages));
     }, [messages]);
 
+    useEffect(() => {
+        debugAgentChat('stream state', {
+            agentRunId,
+            messageCount: messages.length,
+            streamingCount: streamingMessages.size,
+            initialHistoryStatus,
+            isCompleted,
+            lastDeliveredTs: lastDeliveredTsRef.current,
+            first: summarizeMessage(messages[0]),
+            last: summarizeMessage(messages[messages.length - 1]),
+        });
+    }, [agentRunId, initialHistoryStatus, isCompleted, messages, streamingMessages.size]);
+
     // Stream messages from the agent
     useEffect(() => {
         // A nonce bump reconnects the current conversation without clearing the timeline.
@@ -132,6 +300,7 @@ export function useAgentStream(client: VertesiaClient, agentRunId: string): UseA
 
         if (isNewConversation) {
             setMessages([]);
+            setInitialHistoryStatus('loading');
             setAgentRunStatus(null);
             setWorkflowRunId(null);
             setStreamingMessages(new Map());
@@ -144,12 +313,23 @@ export function useAgentStream(client: VertesiaClient, agentRunId: string): UseA
         // new conversation. The cursor is exclusive server-side (ts > since), so the prior
         // run's terminal message is skipped on reconnect.
         const since = isNewConversation ? undefined : lastDeliveredTsRef.current || undefined;
+        debugAgentChat('stream start', {
+            agentRunId,
+            isNewConversation,
+            since,
+            streamNonce,
+        });
 
         // Check agent run status
         client.agents
             .getInternals(agentRunId)
             .then((agentRun) => {
                 if (!abortController.signal.aborted) {
+                    debugAgentChat('internals loaded', {
+                        agentRunId,
+                        status: agentRun.status,
+                        first_workflow_run_id: agentRun.first_workflow_run_id,
+                    });
                     setAgentRunStatus(agentRun.status?.toUpperCase() ?? null);
                     setWorkflowRunId(agentRun.first_workflow_run_id ?? null);
                 }
@@ -166,6 +346,16 @@ export function useAgentStream(client: VertesiaClient, agentRunId: string): UseA
                 (message) => {
                     if (abortController.signal.aborted) return;
 
+                    debugAgentChat('stream message', {
+                        agentRunId,
+                        type: message.type,
+                        timestamp: message.timestamp,
+                        workstream_id: message.workstream_id,
+                        hasMessage: Boolean(message.message),
+                        display_role: message.details?.display_role,
+                        source: message.details?.source,
+                    });
+
                     // Advance the reconnect cursor past every delivered message.
                     if (message.timestamp && message.timestamp > lastDeliveredTsRef.current) {
                         lastDeliveredTsRef.current = message.timestamp;
@@ -175,7 +365,7 @@ export function useAgentStream(client: VertesiaClient, agentRunId: string): UseA
                     // PERFORMANCE: Batch updates using RAF instead of immediate state updates
                     if (message.type === AgentMessageType.STREAMING_CHUNK) {
                         const details = message.details as Common.StreamingChunkDetails;
-                        const streamKey = details?.activity_id || details?.streaming_id;
+                        const streamKey = getStreamingChunkKey(message);
                         if (!streamKey) return;
 
                         // Accumulate chunks in the ref (no state update yet)
@@ -184,6 +374,7 @@ export function useAgentStream(client: VertesiaClient, agentRunId: string): UseA
                             workstreamId: message.workstream_id,
                             startTimestamp: Date.now(),
                             activityId: details?.activity_id,
+                            streamingId: details?.streaming_id,
                         };
                         const newText = current.text + (message.message || '');
 
@@ -193,6 +384,7 @@ export function useAgentStream(client: VertesiaClient, agentRunId: string): UseA
                             isComplete: details.is_final,
                             startTimestamp: current.startTimestamp,
                             activityId: details?.activity_id,
+                            streamingId: details?.streaming_id,
                         });
 
                         // Schedule a flush if not already scheduled (~60 updates/sec max)
@@ -223,21 +415,22 @@ export function useAgentStream(client: VertesiaClient, agentRunId: string): UseA
                         // Other SYSTEM messages fall through to normal handling
                     }
 
-                    // When THOUGHT or ANSWER arrives with activity_id, remove matching streaming message
-                    if (
-                        (message.type === AgentMessageType.THOUGHT || message.type === AgentMessageType.ANSWER) &&
-                        message.details?.activity_id
-                    ) {
-                        const activityId = message.details.activity_id as string;
-                        pendingStreamingChunks.current.delete(activityId);
-                        setStreamingMessages((prev) => {
-                            if (prev.has(activityId)) {
-                                const next = new Map(prev);
-                                next.delete(activityId);
-                                return next;
+                    // When THOUGHT or ANSWER arrives, remove matching live streaming content.
+                    if (message.type === AgentMessageType.THOUGHT || message.type === AgentMessageType.ANSWER) {
+                        const replacementKeys = getStreamingReplacementKeys(message);
+                        if (replacementKeys.length > 0) {
+                            for (const key of replacementKeys) {
+                                pendingStreamingChunks.current.delete(key);
                             }
-                            return prev;
-                        });
+                            setStreamingMessages((prev) => {
+                                const next = new Map(prev);
+                                let changed = false;
+                                for (const key of replacementKeys) {
+                                    changed = next.delete(key) || changed;
+                                }
+                                return changed ? next : prev;
+                            });
+                        }
                     }
 
                     // On COMPLETE or IDLE, flush any pending chunks
@@ -247,37 +440,45 @@ export function useAgentStream(client: VertesiaClient, agentRunId: string): UseA
                         }
                     }
 
-                    const hasContent = !!message.message;
-                    const isStateMessage = [
-                        AgentMessageType.COMPLETE,
-                        AgentMessageType.IDLE,
-                        AgentMessageType.TERMINATED,
-                        AgentMessageType.REQUEST_INPUT,
-                    ].includes(message.type);
-
-                    if (hasContent || isStateMessage) {
-                        setMessages((prev) => {
-                            // Check for duplicate by timestamp
-                            if (prev.find((m) => m.timestamp === message.timestamp)) {
-                                return prev;
-                            }
-
-                            // For QUESTION messages from server, replace any optimistic version
-                            if (message.type === AgentMessageType.QUESTION && !message.details?._optimistic) {
-                                const withoutOptimistic = prev.filter(
-                                    (m) => !(m.type === AgentMessageType.QUESTION && m.details?._optimistic),
-                                );
-                                insertMessageInTimeline(withoutOptimistic, message);
-                                return [...withoutOptimistic];
-                            }
-
-                            insertMessageInTimeline(prev, message);
-                            return [...prev];
-                        });
+                    if (shouldStoreTimelineMessage(message)) {
+                        setMessages((prev) => insertTimelineMessage(prev, message));
                     }
                 },
                 since,
                 abortController.signal,
+                {
+                    onHistoryLoaded: (historical) => {
+                        if (abortController.signal.aborted) return;
+                        const timelineMessages = historical.filter(shouldStoreTimelineMessage);
+                        debugAgentChat('history loaded', {
+                            agentRunId,
+                            count: historical.length,
+                            timelineCount: timelineMessages.length,
+                            since,
+                            first: summarizeMessage(historical[0]),
+                            last: summarizeMessage(historical[historical.length - 1]),
+                        });
+                        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),
+                            );
+                        }
+                    },
+                    onHistoryError: (error) => {
+                        if (abortController.signal.aborted) return;
+                        debugAgentChat('history error', {
+                            agentRunId,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                        setInitialHistoryStatus('error');
+                    },
+                },
             )
             .then(() => {
                 // The stream resolves when the run reaches a terminal state. The status was
@@ -285,10 +486,15 @@ export function useAgentStream(client: VertesiaClient, agentRunId: string): UseA
                 // authoritative status now — otherwise a run that FAILS while the panel is
                 // open never surfaces the failed UI until the conversation is remounted.
                 if (abortController.signal.aborted) return undefined;
+                debugAgentChat('stream resolved', { agentRunId });
                 return client.agents
                     .getInternals(agentRunId)
                     .then((agentRun) => {
                         if (!abortController.signal.aborted) {
+                            debugAgentChat('internals refreshed after stream end', {
+                                agentRunId,
+                                status: agentRun.status,
+                            });
                             setAgentRunStatus(agentRun.status?.toUpperCase() ?? null);
                         }
                     })
@@ -300,11 +506,16 @@ export function useAgentStream(client: VertesiaClient, agentRunId: string): UseA
             })
             .catch((error) => {
                 if (!abortController.signal.aborted) {
+                    debugAgentChat('stream failed', {
+                        agentRunId,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
                     console.error('Failed to stream agent messages:', error);
                 }
             });
 
         return () => {
+            debugAgentChat('stream cleanup', { agentRunId, streamNonce });
             abortController.abort();
             // Note: messages are intentionally NOT cleared here. Switching conversations
             // resets them at effect start (isNewConversation); a reconnect must preserve
@@ -346,6 +557,20 @@ export function useAgentStream(client: VertesiaClient, agentRunId: string): UseA
         });
     }, []);
 
+    const updateOptimisticMessageStatus = useCallback(
+        (messageId: string, status: NonNullable<Common.AgentMessageDetails['_deliveryStatus']>) => {
+            setMessages((prev) =>
+                prev.map((message) => {
+                    if (message.details?._optimistic && getClientMessageId(message) === messageId) {
+                        return withDeliveryStatus(message, status);
+                    }
+                    return message;
+                }),
+            );
+        },
+        [],
+    );
+
     // Remove optimistic messages matching a predicate
     const removeOptimisticMessages = useCallback((predicate: (msg: AgentMessage) => boolean) => {
         setMessages((prev) => prev.filter((m) => !predicate(m)));
@@ -355,8 +580,10 @@ export function useAgentStream(client: VertesiaClient, agentRunId: string): UseA
         messages,
         streamingMessages,
         isCompleted,
+        initialHistoryStatus,
         debugChunkFlash,
         addOptimisticMessage,
+        updateOptimisticMessageStatus,
         removeOptimisticMessages,
         reconnect,
         agentRunStatus,

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

@@ -15,31 +15,14 @@ export interface ArtifactTreeNode {
 }
 
 // ---------------------------------------------------------------------------
-// System artifacts — agent execution internals (tool I/O hydration,
-// conversation snapshots, process state, archives). Hidden by default and
-// revealed via the "Show system files" toggle.
+// Internal files we never show to the user
 // ---------------------------------------------------------------------------
 
-// Matched against the run-relative path: any path with one of these directory
-// segments is agent scaffolding rather than a user-facing output.
-const SYSTEM_DIR_PATTERN = /(^|\/)(tool-inputs|tool-results|archive)(\/|$)/;
-const SYSTEM_PROCESS_PATTERN = /(^|\/)process\/(history|state)(\/|$)/;
-
-// Matched against the file basename.
-const SYSTEM_BASENAME_PATTERNS = [
-    /conversation\.json$/, // conversation.json, <id>-conversation.json
-    /^conversation-checkpoint-\d+\.json$/,
-    /^tools\.json$/,
-    /^tool-input-refs\.json$/,
-    /^toolu[_-]/i, // per-tool-use input/result hydration payloads
-];
-
-export function isSystemArtifact(relativePath: string): boolean {
-    if (SYSTEM_DIR_PATTERN.test(relativePath) || SYSTEM_PROCESS_PATTERN.test(relativePath)) {
-        return true;
-    }
+const INTERNAL_FILE_PATTERNS = [/conversation\.json$/, /-conversation\.json$/, /^tools\.json$/];
+
+function isInternalFile(relativePath: string): boolean {
     const basename = relativePath.split('/').pop() ?? relativePath;
-    return SYSTEM_BASENAME_PATTERNS.some((re) => re.test(basename));
+    return INTERNAL_FILE_PATTERNS.some((re) => re.test(basename));
 }
 
 // ---------------------------------------------------------------------------
@@ -105,26 +88,15 @@ function stripToRelativePath(fullPath: string, runId: string): string {
 // ---------------------------------------------------------------------------
 
 export interface UseArtifactsResult {
-    /** Tree of the currently visible files (respects `showSystem`). */
     tree: ArtifactTreeNode[];
-    /** Currently visible files (respects `showSystem`). */
     flatFiles: string[];
-    /** Total number of artifacts in the run, including system files. */
-    totalCount: number;
-    /** Number of system files currently hidden (0 when `showSystem` is true). */
-    systemHiddenCount: number;
     isLoading: boolean;
     error: string | null;
     refresh: () => void;
 }
 
-export function useArtifacts(
-    client: VertesiaClient,
-    runId: string | undefined,
-    refreshKey = 0,
-    showSystem = false,
-): UseArtifactsResult {
-    const [allFiles, setAllFiles] = useState<string[]>([]);
+export function useArtifacts(client: VertesiaClient, runId: string | undefined, refreshKey = 0): UseArtifactsResult {
+    const [flatFiles, setFlatFiles] = useState<string[]>([]);
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState<string | null>(null);
     const [manualRefreshKey, setManualRefreshKey] = useState(0);
@@ -141,13 +113,13 @@ export function useArtifacts(
             const paths = await client.files.listArtifacts(runId);
             if (fetchId !== fetchIdRef.current) return; // stale
 
-            const relatives = paths.map((p) => stripToRelativePath(p, runId)).filter((p) => !!p);
+            const relatives = paths.map((p) => stripToRelativePath(p, runId)).filter((p) => p && !isInternalFile(p));
 
-            setAllFiles(relatives);
+            setFlatFiles(relatives);
         } catch (err) {
             if (fetchId !== fetchIdRef.current) return;
             setError(err instanceof Error ? err.message : 'Failed to list artifacts');
-            setAllFiles([]);
+            setFlatFiles([]);
         } finally {
             if (fetchId === fetchIdRef.current) {
                 setIsLoading(false);
@@ -161,16 +133,11 @@ export function useArtifacts(
         void fetchArtifacts();
     }, [fetchArtifacts, refreshKey, manualRefreshKey]);
 
-    const flatFiles = useMemo(
-        () => (showSystem ? allFiles : allFiles.filter((p) => !isSystemArtifact(p))),
-        [allFiles, showSystem],
-    );
     const tree = useMemo(() => buildTree(flatFiles), [flatFiles]);
-    const systemHiddenCount = allFiles.length - flatFiles.length;
 
     const refresh = useCallback(() => {
         setManualRefreshKey((k) => k + 1);
     }, []);
 
-    return { tree, flatFiles, totalCount: allFiles.length, systemHiddenCount, isLoading, error, refresh };
+    return { tree, flatFiles, isLoading, error, refresh };
 }

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

@@ -1,3 +1,7 @@
+export {
+    AgentApprovalModeSelector,
+    type AgentApprovalModeSelectorProps,
+} from './AgentApprovalModeSelector';
 export {
     AgentChart,
     type AgentChartSpec,
@@ -24,7 +28,12 @@ export {
     type ConfirmationWidgetProps,
 } from './AskUserWidget';
 export * from './JumpingDots';
-export { ModernAgentConversation, type ModernAgentConversationProps } from './ModernAgentConversation';
+export {
+    ModernAgentConversation,
+    type ModernAgentConversationProps,
+    type StartWorkflowFn,
+    type StartWorkflowOptions,
+} from './ModernAgentConversation';
 // AgentConversationViewMode type for external use
 export type {
     AgentConversationViewMode,

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

@@ -180,3 +180,45 @@ export function getWorkstreamLaunchDetails(message: AgentMessage): WorkstreamLau
             typeof details.child_workflow_run_id === 'string' ? details.child_workflow_run_id : undefined,
     };
 }
+
+export function getWorkstreamActivityDetails(message: AgentMessage): WorkstreamLaunchDetails | null {
+    const details = message.details as
+        | {
+              event_class?: unknown;
+              workstream_event?: unknown;
+              workstream_id?: unknown;
+              launch_id?: unknown;
+              kind?: unknown;
+              interaction?: unknown;
+              child_workflow_id?: unknown;
+              child_workflow_run_id?: unknown;
+          }
+        | undefined;
+
+    if (details?.event_class !== 'activity') return null;
+    if (details.workstream_event !== undefined) return null;
+    if (message.type === AgentMessageType.ERROR) return null;
+
+    const childWorkflowId = typeof details.child_workflow_id === 'string' ? details.child_workflow_id : undefined;
+    const childWorkflowRunId =
+        typeof details.child_workflow_run_id === 'string' ? details.child_workflow_run_id : undefined;
+    if (!childWorkflowId && !childWorkflowRunId) return null;
+
+    const workstreamId =
+        typeof details.workstream_id === 'string' && details.workstream_id.trim()
+            ? details.workstream_id
+            : typeof message.workstream_id === 'string'
+              ? message.workstream_id
+              : '';
+
+    if (!isNonMainWorkstreamId(workstreamId)) return null;
+
+    return {
+        workstreamId,
+        launchId: typeof details.launch_id === 'string' ? details.launch_id : undefined,
+        kind: typeof details.kind === 'string' ? details.kind : undefined,
+        interaction: typeof details.interaction === 'string' ? details.interaction : undefined,
+        childWorkflowId,
+        childWorkflowRunId,
+    };
+}

package/src/features/facets/AgentRunnerFacetsNav.tsx

@@ -25,6 +25,15 @@ interface AgentRunnerFacetsNavProps {
     search: SearchInterface;
     actions?: React.ReactNode[];
     selectionCount?: number;
+    /**
+     * Optional controlled filter state. When provided, the parent owns the filter list so other
+     * surfaces — e.g. per-row "quick filter" buttons in the table — can add filters that show up in
+     * the filter bar. The filter→query translation still happens inside this component, so the parent
+     * only needs a plain state setter. When omitted, the component manages its own filter state.
+     */
+    filters?: BaseFilter[];
+    setFilters?: React.Dispatch<React.SetStateAction<BaseFilter[]>>;
+    filterGroups?: FilterGroup[];
 }
 
 // Hook to create filter groups for agent runners
@@ -98,13 +107,24 @@ export function createAgentRunnerFilterHandler(search: SearchInterface) {
 }
 
 // Legacy component for backward compatibility
-export function AgentRunnerFacetsNav({ facets, search, selectionCount, actions }: AgentRunnerFacetsNavProps) {
-    const [filters, setFilters] = useState<BaseFilter[]>([]);
+export function AgentRunnerFacetsNav({
+    facets,
+    search,
+    selectionCount,
+    actions,
+    filters: controlledFilters,
+    setFilters: controlledSetFilters,
+    filterGroups: controlledFilterGroups,
+}: AgentRunnerFacetsNavProps) {
+    const [internalFilters, setInternalFilters] = useState<BaseFilter[]>([]);
+    const filters = controlledFilters ?? internalFilters;
+    const setFilters = controlledSetFilters ?? setInternalFilters;
     const didMountRef = useRef(false);
     const skipNextSearchRef = useRef(
         typeof window !== 'undefined' && Boolean(new URLSearchParams(window.location.search).get('filters')),
     );
-    const filterGroups = useAgentRunnerFilterGroups(facets);
+    const internalFilterGroups = useAgentRunnerFilterGroups(facets);
+    const filterGroups = controlledFilterGroups ?? internalFilterGroups;
     const handleFilterLogic = useMemo(() => createAgentRunnerFilterHandler(search), [search]);
 
     useEffect(() => {