flock-core 0.5.2__py3-none-any.whl → 0.5.4__py3-none-any.whl

flock/frontend/src/components/graph/PendingJoinEdge.tsx

@@ -0,0 +1,144 @@
+import React from 'react';
+import {
+  BaseEdge,
+  EdgeProps,
+  getBezierPath,
+  getStraightPath,
+  getSmoothStepPath,
+  getSimpleBezierPath,
+  EdgeLabelRenderer
+} from '@xyflow/react';
+import { useSettingsStore } from '../../store/settingsStore';
+
+/**
+ * Phase 1.5: Logic Operations UX - PendingJoinEdge Component
+ *
+ * Custom edge for showing artifacts "en route" to JoinSpec correlation groups.
+ * Visually distinct from normal message_flow edges to indicate waiting state.
+ *
+ * Features:
+ * - Purple dashed line (matches JoinSpec theme)
+ * - Label with ⋈ symbol + correlation key
+ * - Hover tooltip showing waiting_for types
+ * - Animated dashing to show "pending" state
+ *
+ * Edge type: "pending_join"
+ * Created by backend graph_builder.py when artifacts are waiting in correlation groups
+ */
+
+export interface PendingJoinEdgeData {
+  artifactId: string;
+  artifactType: string;
+  correlationKey: string;
+  subscriptionIndex: number;
+  waitingFor: string[];
+  labelOffset?: number;
+}
+
+const PendingJoinEdge: React.FC<EdgeProps> = ({
+  id,
+  sourceX,
+  sourceY,
+  targetX,
+  targetY,
+  sourcePosition,
+  targetPosition,
+  label,
+  style = {},
+  markerEnd,
+  data,
+}) => {
+  // Get edge settings from settings store
+  const edgeType = useSettingsStore((state) => state.graph.edgeType);
+  const edgeStrokeWidth = useSettingsStore((state) => state.graph.edgeStrokeWidth);
+  const showEdgeLabels = useSettingsStore((state) => state.graph.showEdgeLabels);
+
+  // Use appropriate path function based on settings
+  const getPath = () => {
+    const params = { sourceX, sourceY, sourcePosition, targetX, targetY, targetPosition };
+    switch (edgeType) {
+      case 'straight':
+        return getStraightPath(params);
+      case 'smoothstep':
+        return getSmoothStepPath(params);
+      case 'simplebezier':
+        return getSimpleBezierPath(params);
+      case 'bezier':
+      default:
+        return getBezierPath(params);
+    }
+  };
+
+  const [edgePath, labelX, labelY] = getPath();
+
+  const edgeData = data as PendingJoinEdgeData | undefined;
+  const labelOffset = edgeData?.labelOffset || 0;
+  const waitingFor = edgeData?.waitingFor || [];
+
+  const [isHovered, setIsHovered] = React.useState(false);
+
+  // Purple color theme for JoinSpec
+  const edgeColor = 'var(--color-purple-500, #a855f7)';
+  const edgeColorHover = 'var(--color-purple-600, #9333ea)';
+
+  return (
+    <>
+      <BaseEdge
+        id={id}
+        path={edgePath}
+        style={{
+          ...style,
+          stroke: isHovered ? edgeColorHover : edgeColor,
+          strokeWidth: isHovered ? edgeStrokeWidth + 1 : edgeStrokeWidth,
+          strokeDasharray: '8,6', // Dashed line for "pending" state
+          opacity: 0.7,
+          transition: 'var(--transition-all)',
+          filter: isHovered ? `drop-shadow(0 0 6px ${edgeColor})` : 'none',
+          animation: 'pending-dash 2s linear infinite',
+        }}
+        markerEnd={markerEnd}
+      />
+      {label && showEdgeLabels && (
+        <EdgeLabelRenderer>
+          <div
+            style={{
+              position: 'absolute',
+              transform: `translate(-50%, -50%) translate(${labelX}px,${labelY + labelOffset}px)`,
+              fontSize: 'var(--font-size-caption)',
+              fontWeight: 'var(--font-weight-semibold)',
+              background: 'rgba(168, 85, 247, 0.12)', // Purple tinted background
+              color: 'var(--color-purple-700, #7e22ce)',
+              padding: '4px 8px',
+              borderRadius: 'var(--radius-sm)',
+              border: `1.5px dashed ${edgeColor}`,
+              pointerEvents: 'all',
+              backdropFilter: 'blur(var(--blur-sm))',
+              boxShadow: isHovered ? 'var(--shadow-md)' : 'var(--shadow-xs)',
+              transition: 'var(--transition-all)',
+              cursor: 'help',
+            }}
+            className="nodrag nopan"
+            onMouseEnter={() => setIsHovered(true)}
+            onMouseLeave={() => setIsHovered(false)}
+            title={
+              waitingFor.length > 0
+                ? `Waiting for: ${waitingFor.join(', ')}\nArtifact: ${edgeData?.artifactType || 'unknown'}`
+                : `Correlation pending\nArtifact: ${edgeData?.artifactType || 'unknown'}`
+            }
+          >
+            {label}
+          </div>
+        </EdgeLabelRenderer>
+      )}
+      <style>{`
+        @keyframes pending-dash {
+          to {
+            stroke-dashoffset: -28;
+          }
+        }
+      `}</style>
+    </>
+  );
+};
+
+export default PendingJoinEdge;

flock/frontend/src/services/graphService.ts

@@ -57,7 +57,8 @@ function randomPosition() {
 export function overlayWebSocketState(
   nodes: Node[],
   agentStatus: Map<string, string>,
-  streamingTokens: Map<string, string[]>
+  streamingTokens: Map<string, string[]>,
+  agentLogicOperations?: Map<string, any[]>
 ): Node[] {
   return nodes.map(node => {
     if (node.type === 'agent') {
@@ -67,6 +68,7 @@ export function overlayWebSocketState(
           ...node.data,
           status: agentStatus.get(node.id) || node.data.status,
           streamingTokens: streamingTokens.get(node.id) || [],
+          logicOperations: agentLogicOperations?.get(node.id) || node.data.logicOperations || [],
         },
       };
     }

flock/frontend/src/services/websocket.ts

@@ -3,7 +3,7 @@ import { useGraphStore } from '../store/graphStore';
 import { useFilterStore } from '../store/filterStore';
 
 interface WebSocketMessage {
-  event_type: 'agent_activated' | 'message_published' | 'streaming_output' | 'agent_completed' | 'agent_error';
+  event_type: 'agent_activated' | 'message_published' | 'streaming_output' | 'agent_completed' | 'agent_error' | 'correlation_group_updated' | 'batch_item_added';
   timestamp: string;
   correlation_id: string;
   session_id: string;
@@ -282,6 +282,104 @@ export class WebSocketClient {
     this.on('ping', () => {
       this.send({ type: 'pong', timestamp: Date.now() });
     });
+
+    // Phase 1.3: Handler for correlation_group_updated - update logic operations state
+    this.on('correlation_group_updated', (data) => {
+      const { agent_name, subscription_index, correlation_key, elapsed_seconds, expires_in_seconds, waiting_for } = data;
+
+      console.log('[WebSocket] Correlation group updated:', {
+        agent: agent_name,
+        key: correlation_key,
+        waiting_for,
+        elapsed: elapsed_seconds,
+        expires_in: expires_in_seconds,
+      });
+
+      // Get current logic operations for this agent
+      const graphStore = useGraphStore.getState();
+      const currentLogicOps = graphStore.agentLogicOperations.get(agent_name) || [];
+
+      // Find the subscription's logic operations
+      const updatedLogicOps = currentLogicOps.map((logicOp) => {
+        if (logicOp.subscription_index === subscription_index && logicOp.join) {
+          // Update waiting_state with correlation group data
+          const correlationGroup = {
+            correlation_key: data.correlation_key,
+            created_at: data.timestamp,
+            elapsed_seconds: data.elapsed_seconds,
+            expires_in_seconds: data.expires_in_seconds,
+            expires_in_artifacts: data.expires_in_artifacts,
+            collected_types: data.collected_types,
+            required_types: data.required_types,
+            waiting_for: data.waiting_for,
+            is_complete: data.is_complete,
+            is_expired: false,
+          };
+
+          return {
+            ...logicOp,
+            waiting_state: {
+              is_waiting: true,
+              correlation_groups: [correlationGroup],
+            },
+          };
+        }
+        return logicOp;
+      });
+
+      // Update graph store with new logic operations state
+      if (updatedLogicOps.length > 0) {
+        graphStore.updateAgentLogicOperations(agent_name, updatedLogicOps);
+      }
+    });
+
+    // Phase 1.3: Handler for batch_item_added - update logic operations state
+    this.on('batch_item_added', (data) => {
+      const { agent_name, subscription_index, items_collected, items_target, timeout_remaining_seconds, will_flush } = data;
+
+      console.log('[WebSocket] Batch item added:', {
+        agent: agent_name,
+        collected: items_collected,
+        target: items_target,
+        timeout_remaining: timeout_remaining_seconds,
+        will_flush,
+      });
+
+      // Get current logic operations for this agent
+      const graphStore = useGraphStore.getState();
+      const currentLogicOps = graphStore.agentLogicOperations.get(agent_name) || [];
+
+      // Find the subscription's logic operations
+      const updatedLogicOps = currentLogicOps.map((logicOp) => {
+        if (logicOp.subscription_index === subscription_index && logicOp.batch) {
+          // Update waiting_state with batch data
+          const batchState = {
+            created_at: data.timestamp,
+            elapsed_seconds: data.elapsed_seconds,
+            items_collected: data.items_collected,
+            items_target: data.items_target,
+            items_remaining: data.items_remaining,
+            timeout_seconds: data.timeout_seconds,
+            timeout_remaining_seconds: data.timeout_remaining_seconds,
+            will_flush: data.will_flush,
+          };
+
+          return {
+            ...logicOp,
+            waiting_state: {
+              is_waiting: true,
+              batch_state: batchState,
+            },
+          };
+        }
+        return logicOp;
+      });
+
+      // Update graph store with new logic operations state
+      if (updatedLogicOps.length > 0) {
+        graphStore.updateAgentLogicOperations(agent_name, updatedLogicOps);
+      }
+    });
   }
 
   connect(): void {

flock/frontend/src/store/graphStore.test.ts

@@ -468,7 +468,8 @@ describe('graphStore - NEW Simplified Architecture', () => {
       expect(overlayWebSocketState).toHaveBeenCalledWith(
         mockMergedNodes,
         expect.any(Map), // agentStatus
-        expect.any(Map) // streamingTokens
+        expect.any(Map), // streamingTokens
+        expect.any(Map) // agentLogicOperations
       );
     });
   });

flock/frontend/src/store/graphStore.ts

@@ -1,7 +1,7 @@
 import { create } from 'zustand';
 import { devtools } from 'zustand/middleware';
 import { Node, Edge } from '@xyflow/react';
-import { GraphSnapshot, GraphStatistics, GraphRequest } from '../types/graph';
+import { GraphSnapshot, GraphStatistics, GraphRequest, AgentLogicOperations } from '../types/graph';
 import { fetchGraphSnapshot, mergeNodePositions, overlayWebSocketState } from '../services/graphService';
 import { useFilterStore } from './filterStore';
 import { Message } from '../types/graph';
@@ -20,12 +20,17 @@ import { indexedDBService } from '../services/indexeddb';
  * - Debounced refresh: 100ms batching for snappy UX
  * - No more client-side edge derivation
  * - No more synthetic runs or complex Maps
+ *
+ * Phase 1.3: Logic Operations UX
+ * - Added logic operations state for JoinSpec/BatchSpec waiting states
+ * - Real-time updates via CorrelationGroupUpdatedEvent and BatchItemAddedEvent
  */
 
 interface GraphState {
   // Real-time WebSocket state (overlaid on backend snapshot)
   agentStatus: Map<string, string>;
   streamingTokens: Map<string, string[]>;
+  agentLogicOperations: Map<string, AgentLogicOperations[]>; // Phase 1.3: Logic operations state
 
   // Backend snapshot state
   nodes: Node[];
@@ -52,6 +57,7 @@ interface GraphState {
   // Actions - Real-time WebSocket updates
   updateAgentStatus: (agentId: string, status: string) => void;
   updateStreamingTokens: (agentId: string, tokens: string[]) => void;
+  updateAgentLogicOperations: (agentId: string, logicOps: AgentLogicOperations[]) => void; // Phase 1.3
   addEvent: (message: Message) => void;
 
   // Actions - Streaming message nodes (Phase 6)
@@ -118,6 +124,7 @@ export const useGraphStore = create<GraphState>()(
       // Initial state
       agentStatus: new Map(),
       streamingTokens: new Map(),
+      agentLogicOperations: new Map(), // Phase 1.3
       nodes: [],
       edges: [],
       statistics: null,
@@ -138,13 +145,13 @@ export const useGraphStore = create<GraphState>()(
           const request = buildGraphRequest('agent');
           const snapshot: GraphSnapshot = await fetchGraphSnapshot(request);
 
-          const { savedPositions, nodes: currentNodes, agentStatus, streamingTokens } = get();
+          const { savedPositions, nodes: currentNodes, agentStatus, streamingTokens, agentLogicOperations } = get();
 
           // Merge positions: saved > current > backend > random
           const mergedNodes = mergeNodePositions(snapshot.nodes, savedPositions, currentNodes);
 
           // Overlay real-time WebSocket state
-          const finalNodes = overlayWebSocketState(mergedNodes, agentStatus, streamingTokens);
+          const finalNodes = overlayWebSocketState(mergedNodes, agentStatus, streamingTokens, agentLogicOperations);
 
           set({
             nodes: finalNodes,
@@ -193,13 +200,13 @@ export const useGraphStore = create<GraphState>()(
           const request = buildGraphRequest('blackboard');
           const snapshot: GraphSnapshot = await fetchGraphSnapshot(request);
 
-          const { savedPositions, nodes: currentNodes, agentStatus, streamingTokens } = get();
+          const { savedPositions, nodes: currentNodes, agentStatus, streamingTokens, agentLogicOperations } = get();
 
           // Merge positions: saved > current > backend > random
           const mergedNodes = mergeNodePositions(snapshot.nodes, savedPositions, currentNodes);
 
           // Overlay real-time WebSocket state (primarily for message streaming)
-          const finalNodes = overlayWebSocketState(mergedNodes, agentStatus, streamingTokens);
+          const finalNodes = overlayWebSocketState(mergedNodes, agentStatus, streamingTokens, agentLogicOperations);
 
           set({
             nodes: finalNodes,
@@ -309,6 +316,30 @@ export const useGraphStore = create<GraphState>()(
         });
       },
 
+      // Phase 1.3: Logic Operations UX - Update agent logic operations state
+      updateAgentLogicOperations: (agentId, logicOps) => {
+        set((state) => {
+          const agentLogicOperations = new Map(state.agentLogicOperations);
+          agentLogicOperations.set(agentId, logicOps);
+
+          // Update agent nodes with logic operations data
+          const nodes = state.nodes.map(node => {
+            if (node.type === 'agent' && node.id === agentId) {
+              return {
+                ...node,
+                data: {
+                  ...node.data,
+                  logicOperations: logicOps,
+                },
+              };
+            }
+            return node;
+          });
+
+          return { agentLogicOperations, nodes };
+        });
+      },
+
       addEvent: (message) => {
         set((state) => {
           // Add to events array (max 100 items)

flock/frontend/src/types/graph.ts

@@ -93,3 +93,89 @@ export interface ArtifactSummary {
   earliest_created_at: string;
   latest_created_at: string;
 }
+
+// Phase 1.3: Logic Operations UX - Real-time WebSocket Events
+export interface CorrelationGroupUpdatedEvent {
+  timestamp: string;
+  agent_name: string;
+  subscription_index: number;
+  correlation_key: string;
+  collected_types: Record<string, number>;
+  required_types: Record<string, number>;
+  waiting_for: string[];
+  elapsed_seconds: number;
+  expires_in_seconds: number | null;
+  expires_in_artifacts: number | null;
+  artifact_id: string;
+  artifact_type: string;
+  is_complete: boolean;
+}
+
+export interface BatchItemAddedEvent {
+  timestamp: string;
+  agent_name: string;
+  subscription_index: number;
+  items_collected: number;
+  items_target: number | null;
+  items_remaining: number | null;
+  elapsed_seconds: number;
+  timeout_seconds: number | null;
+  timeout_remaining_seconds: number | null;
+  will_flush: 'on_size' | 'on_timeout' | 'unknown';
+  artifact_id: string;
+  artifact_type: string;
+}
+
+// Agent logic operations state (from /api/agents endpoint + WebSocket updates)
+export interface AgentLogicOperations {
+  subscription_index: number;
+  subscription_types: string[];
+  join?: JoinSpecConfig;
+  batch?: BatchSpecConfig;
+  waiting_state?: LogicOperationsWaitingState;
+}
+
+export interface JoinSpecConfig {
+  correlation_strategy: 'by_key';
+  window_type: 'time' | 'count';
+  window_value: number;
+  window_unit: 'seconds' | 'artifacts';
+  required_types: string[];
+  type_counts: Record<string, number>;
+}
+
+export interface BatchSpecConfig {
+  strategy: 'size' | 'timeout' | 'hybrid';
+  size?: number;
+  timeout_seconds?: number;
+}
+
+export interface LogicOperationsWaitingState {
+  is_waiting: boolean;
+  correlation_groups?: CorrelationGroupState[];
+  batch_state?: BatchState;
+}
+
+export interface CorrelationGroupState {
+  correlation_key: string;
+  created_at: string;
+  elapsed_seconds: number;
+  expires_in_seconds: number | null;
+  expires_in_artifacts: number | null;
+  collected_types: Record<string, number>;
+  required_types: Record<string, number>;
+  waiting_for: string[];
+  is_complete: boolean;
+  is_expired: boolean;
+}
+
+export interface BatchState {
+  created_at: string;
+  elapsed_seconds: number;
+  items_collected: number;
+  items_target: number | null;
+  items_remaining: number | null;
+  timeout_seconds?: number;
+  timeout_remaining_seconds?: number;
+  will_flush: 'on_size' | 'on_timeout' | 'unknown';
+}