flock-core 0.5.11__py3-none-any.whl → 0.5.21__py3-none-any.whl

flock/orchestrator/context_builder.py

@@ -0,0 +1,167 @@
+"""Execution context building with security boundary enforcement.
+
+Phase 5A: Extracted from orchestrator.py to eliminate code duplication.
+
+This module implements the security boundary pattern for context creation,
+consolidating duplicated code from direct_invoke(), invoke(), and _run_agent_task().
+
+SECURITY CRITICAL: This module enforces the Phase 8 context provider pattern
+that prevents identity spoofing and READ capability bypass.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+from uuid import UUID, uuid4
+
+
+if TYPE_CHECKING:
+    from flock.core import Agent
+    from flock.core.artifacts import Artifact
+    from flock.core.store import BlackboardStore
+    from flock.utils.runtime import Context
+
+
+class ContextBuilder:
+    """Builds execution contexts with security boundary enforcement.
+
+    This module implements the security boundary pattern:
+    1. Resolve provider (agent > global > default)
+    2. Wrap with BoundContextProvider (prevent identity spoofing)
+    3. Evaluate context artifacts (orchestrator controls READ)
+    4. Create Context with data-only (no capabilities)
+
+    Phase 5A: Extracted to eliminate duplication across 3 methods and
+    reduce _run_agent_task complexity from C(11) to B or A.
+
+    SECURITY NOTICE: Changes to this module affect the security boundary
+    between agents and the blackboard. Review carefully.
+    """
+
+    def __init__(
+        self,
+        *,
+        store: BlackboardStore,
+        default_context_provider: Any | None = None,
+    ):
+        """Initialize ContextBuilder with blackboard store and default provider.
+
+        Args:
+            store: BlackboardStore instance for context provider queries
+            default_context_provider: Global context provider (Phase 3 security fix).
+                If None, agents use DefaultContextProvider. Can be overridden per-agent.
+        """
+        self._store = store
+        self._default_context_provider = default_context_provider
+        self._logger = logging.getLogger(__name__)
+
+    async def build_execution_context(
+        self,
+        *,
+        agent: Agent,
+        artifacts: list[Artifact],
+        correlation_id: UUID | None = None,
+        is_batch: bool = False,
+    ) -> Context:
+        """Build Context with pre-filtered artifacts (Phase 8 security fix).
+
+        Implements the security boundary pattern:
+        1. Resolve provider (agent > global > default)
+        2. Wrap with BoundContextProvider (prevent identity spoofing)
+        3. Evaluate context artifacts (orchestrator controls READ)
+        4. Create Context with data-only (no capabilities)
+
+        SECURITY NOTICE: This method enforces the security boundary between
+        agents and the blackboard. Agents receive pre-filtered context data
+        and cannot bypass visibility controls.
+
+        Args:
+            agent: Agent instance being executed
+            artifacts: Input artifacts that triggered execution
+            correlation_id: Optional correlation ID for grouping related work
+            is_batch: Whether this is a batch execution (affects context metadata)
+
+        Returns:
+            Context with pre-filtered artifacts and agent identity
+
+        Examples:
+            >>> # Direct invocation
+            >>> context = await builder.build_execution_context(
+            ...     agent=pizza_agent,
+            ...     artifacts=[input_artifact],
+            ...     correlation_id=uuid4(),
+            ...     is_batch=False,
+            ... )
+            >>> outputs = await agent.execute(context, artifacts)
+
+            >>> # Batch execution
+            >>> context = await builder.build_execution_context(
+            ...     agent=batch_agent,
+            ...     artifacts=batch_artifacts,
+            ...     correlation_id=batch_correlation,
+            ...     is_batch=True,
+            ... )
+        """
+        # Phase 8: Evaluate context BEFORE creating Context (security fix)
+        # Provider resolution: per-agent > global > DefaultContextProvider
+        from flock.core.context_provider import (
+            BoundContextProvider,
+            ContextRequest,
+            DefaultContextProvider,
+        )
+
+        # Resolve correlation ID
+        resolved_correlation_id = correlation_id or (
+            artifacts[0].correlation_id
+            if artifacts and artifacts[0].correlation_id
+            else uuid4()
+        )
+
+        # Step 1: Resolve provider (agent > global > default)
+        inner_provider = (
+            getattr(agent, "context_provider", None)
+            or self._default_context_provider
+            or DefaultContextProvider()
+        )
+
+        # Step 2: SECURITY FIX - Wrap provider with BoundContextProvider
+        # This prevents identity spoofing by binding the provider to the agent's identity
+        provider = BoundContextProvider(inner_provider, agent.identity)
+
+        # Step 3: Evaluate context using provider (orchestrator controls READ capability)
+        # Engines will receive pre-filtered artifacts via ctx.artifacts
+        request = ContextRequest(
+            agent=agent,
+            correlation_id=resolved_correlation_id,
+            store=self._store,
+            agent_identity=agent.identity,
+            exclude_ids={a.id for a in artifacts},  # Exclude input artifacts
+        )
+        context_artifacts = await provider(request)
+
+        # Step 4: Create Context with pre-filtered data (no capabilities!)
+        # SECURITY: Context is now just data - engines can't query anything
+        from flock.utils.runtime import Context
+
+        ctx = Context(
+            artifacts=context_artifacts,  # Pre-filtered conversation context
+            agent_identity=agent.identity,
+            task_id=str(uuid4()),
+            correlation_id=resolved_correlation_id,
+            is_batch=is_batch,
+        )
+
+        # Log context creation for debugging
+        self._logger.debug(
+            f"Context built: agent={agent.name}, "
+            f"correlation_id={resolved_correlation_id}, "
+            f"is_batch={is_batch}, "
+            f"context_artifacts={len(context_artifacts)}, "
+            f"input_artifacts={len(artifacts)}"
+        )
+
+        return ctx
+
+
+__all__ = ["ContextBuilder"]

flock/{correlation_engine.py → orchestrator/correlation_engine.py}

@@ -16,8 +16,8 @@ from typing import TYPE_CHECKING, Any
 
 
 if TYPE_CHECKING:
-    from flock.artifacts import Artifact
-    from flock.subscription import JoinSpec, Subscription
+    from flock.core.artifacts import Artifact
+    from flock.core.subscription import JoinSpec, Subscription
 
 
 class CorrelationGroup:

flock/orchestrator/event_emitter.py

@@ -0,0 +1,167 @@
+"""Event emission for real-time dashboard updates.
+
+Phase 5A: Extracted from orchestrator.py to reduce coupling to dashboard.
+
+This module handles WebSocket event emission for dashboard visualization of
+batch and correlation logic operations. Separating this code reduces the
+orchestrator's dependency on dashboard-specific components.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    from flock.core.artifacts import Artifact
+    from flock.core.subscription import Subscription
+    from flock.orchestrator.batch_accumulator import BatchEngine
+    from flock.orchestrator.correlation_engine import CorrelationEngine
+
+
+class EventEmitter:
+    """Manages WebSocket event emission for dashboard updates.
+
+    This module is responsible for broadcasting real-time events about
+    batch accumulation and correlation group status to connected dashboard
+    clients via WebSocket.
+
+    Phase 5A: Extracted to reduce orchestrator coupling to dashboard.
+    """
+
+    def __init__(self, websocket_manager: Any | None = None):
+        """Initialize EventEmitter with WebSocket manager.
+
+        Args:
+            websocket_manager: WebSocket manager instance for broadcasting events.
+                If None, event emission is disabled (dashboard not active).
+        """
+        self._websocket_manager = websocket_manager
+
+    def set_websocket_manager(self, websocket_manager: Any | None) -> None:
+        """Update the WebSocket manager (called when dashboard is enabled).
+
+        Args:
+            websocket_manager: WebSocket manager instance for broadcasting
+        """
+        self._websocket_manager = websocket_manager
+
+    async def emit_correlation_updated(
+        self,
+        *,
+        correlation_engine: CorrelationEngine,
+        agent_name: str,
+        subscription_index: int,
+        artifact: Artifact,
+    ) -> None:
+        """Emit CorrelationGroupUpdatedEvent for real-time dashboard updates.
+
+        Called when an artifact is added to a correlation group that is not yet complete.
+
+        Args:
+            correlation_engine: CorrelationEngine instance with current state
+            agent_name: Name of the agent with the JoinSpec subscription
+            subscription_index: Index of the subscription in the agent's subscriptions list
+            artifact: The artifact that triggered this update
+        """
+        # Only emit if dashboard is enabled
+        if self._websocket_manager is None:
+            return
+
+        # Import _get_correlation_groups helper from dashboard service
+        from flock.dashboard.routes.helpers import _get_correlation_groups
+
+        # Get current correlation groups state from engine
+        groups = _get_correlation_groups(
+            correlation_engine, agent_name, subscription_index
+        )
+
+        if not groups:
+            return  # No groups to report (shouldn't happen, but defensive)
+
+        # Find the group that was just updated (match by last updated time or artifact ID)
+        # For now, we'll emit an event for the FIRST group that's still waiting
+        # In practice, the artifact we just added should be in one of these groups
+        for group_state in groups:
+            if not group_state["is_complete"]:
+                # Import CorrelationGroupUpdatedEvent
+                from flock.dashboard.events import CorrelationGroupUpdatedEvent
+
+                # Build and emit event
+                event = CorrelationGroupUpdatedEvent(
+                    agent_name=agent_name,
+                    subscription_index=subscription_index,
+                    correlation_key=group_state["correlation_key"],
+                    collected_types=group_state["collected_types"],
+                    required_types=group_state["required_types"],
+                    waiting_for=group_state["waiting_for"],
+                    elapsed_seconds=group_state["elapsed_seconds"],
+                    expires_in_seconds=group_state["expires_in_seconds"],
+                    expires_in_artifacts=group_state["expires_in_artifacts"],
+                    artifact_id=str(artifact.id),
+                    artifact_type=artifact.type,
+                    is_complete=group_state["is_complete"],
+                )
+
+                # Broadcast via WebSocket
+                await self._websocket_manager.broadcast(event)
+                break  # Only emit one event per artifact addition
+
+    async def emit_batch_item_added(
+        self,
+        *,
+        batch_engine: BatchEngine,
+        agent_name: str,
+        subscription_index: int,
+        subscription: Subscription,
+        artifact: Artifact,
+    ) -> None:
+        """Emit BatchItemAddedEvent for real-time dashboard updates.
+
+        Called when an artifact is added to a batch that hasn't reached flush threshold.
+
+        Args:
+            batch_engine: BatchEngine instance with current state
+            agent_name: Name of the agent with the BatchSpec subscription
+            subscription_index: Index of the subscription in the agent's subscriptions list
+            subscription: The subscription with BatchSpec configuration
+            artifact: The artifact that triggered this update
+        """
+        # Only emit if dashboard is enabled
+        if self._websocket_manager is None:
+            return
+
+        # Import _get_batch_state helper from dashboard service
+        from flock.dashboard.routes.helpers import _get_batch_state
+
+        # Get current batch state from engine
+        batch_state = _get_batch_state(
+            batch_engine, agent_name, subscription_index, subscription.batch
+        )
+
+        if not batch_state:
+            return  # No batch to report (shouldn't happen, but defensive)
+
+        # Import BatchItemAddedEvent
+        from flock.dashboard.events import BatchItemAddedEvent
+
+        # Build and emit event
+        event = BatchItemAddedEvent(
+            agent_name=agent_name,
+            subscription_index=subscription_index,
+            items_collected=batch_state["items_collected"],
+            items_target=batch_state.get("items_target"),
+            items_remaining=batch_state.get("items_remaining"),
+            elapsed_seconds=batch_state["elapsed_seconds"],
+            timeout_seconds=batch_state.get("timeout_seconds"),
+            timeout_remaining_seconds=batch_state.get("timeout_remaining_seconds"),
+            will_flush=batch_state["will_flush"],
+            artifact_id=str(artifact.id),
+            artifact_type=artifact.type,
+        )
+
+        # Broadcast via WebSocket
+        await self._websocket_manager.broadcast(event)
+
+
+__all__ = ["EventEmitter"]

flock/orchestrator/initialization.py

@@ -0,0 +1,184 @@
+"""Orchestrator initialization helper.
+
+Handles component setup and state initialization.
+Extracted from orchestrator.py to reduce __init__ complexity.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from typing import TYPE_CHECKING, Any
+
+from flock.core.store import InMemoryBlackboardStore
+from flock.orchestrator.artifact_collector import ArtifactCollector
+from flock.orchestrator.batch_accumulator import BatchEngine
+from flock.orchestrator.component_runner import ComponentRunner
+from flock.orchestrator.context_builder import ContextBuilder
+from flock.orchestrator.correlation_engine import CorrelationEngine
+from flock.orchestrator.event_emitter import EventEmitter
+from flock.orchestrator.lifecycle_manager import LifecycleManager
+from flock.orchestrator.mcp_manager import MCPManager
+from flock.orchestrator.tracing import TracingManager
+from flock.utils.cli_helper import init_console
+
+
+if TYPE_CHECKING:
+    from flock.components.orchestrator import OrchestratorComponent
+    from flock.core.store import BlackboardStore
+
+
+class OrchestratorInitializer:
+    """Handles orchestrator component initialization.
+
+    Centralizes the complex setup logic from Flock.__init__ into
+    a focused helper class.
+    """
+
+    @staticmethod
+    def initialize_components(
+        store: BlackboardStore | None,
+        context_provider: Any,
+        max_agent_iterations: int,
+        logger: logging.Logger,
+        model: str | None,
+    ) -> dict[str, Any]:
+        """Initialize all orchestrator components and state.
+
+        Args:
+            store: Blackboard storage backend (or None for default)
+            context_provider: Global context provider for agents
+            max_agent_iterations: Circuit breaker limit
+            logger: Logger instance
+            model: Default LLM model
+
+        Returns:
+            Dictionary of initialized components and state
+
+        Examples:
+            >>> logger = logging.getLogger(__name__)
+            >>> components = OrchestratorInitializer.initialize_components(
+            ...     store=None,
+            ...     context_provider=None,
+            ...     max_agent_iterations=1000,
+            ...     logger=logger,
+            ...     model="openai/gpt-4.1",
+            ... )
+            >>> orchestrator.store = components["store"]
+            >>> orchestrator._scheduler = components["scheduler"]
+        """
+        # Initialize console (with error handling for encoding issues)
+        try:
+            init_console(clear_screen=True, show_banner=True, model=model)
+        except (UnicodeEncodeError, UnicodeDecodeError):
+            # Skip banner on Windows consoles with encoding issues (e.g., tests, CI)
+            pass
+
+        # Basic state
+        resolved_store = store or InMemoryBlackboardStore()
+        agents: dict[str, Any] = {}
+        lock = asyncio.Lock()
+        metrics: dict[str, float] = {"artifacts_published": 0, "agent_runs": 0}
+        agent_iteration_count: dict[str, int] = {}
+
+        # Engines
+        artifact_collector = ArtifactCollector()
+        correlation_engine = CorrelationEngine()
+        batch_engine = BatchEngine()
+
+        # Phase 5A modules
+        context_builder = ContextBuilder(
+            store=resolved_store,
+            default_context_provider=context_provider,
+        )
+        event_emitter = EventEmitter(websocket_manager=None)
+        lifecycle_manager = LifecycleManager(
+            correlation_engine=correlation_engine,
+            batch_engine=batch_engine,
+            cleanup_interval=0.1,
+        )
+
+        # Phase 3 modules
+        mcp_manager_instance = MCPManager()
+        tracing_manager = TracingManager()
+
+        # Auto-workflow tracing feature flag
+        auto_workflow_enabled = os.getenv(
+            "FLOCK_AUTO_WORKFLOW_TRACE", "false"
+        ).lower() in {
+            "true",
+            "1",
+            "yes",
+            "on",
+        }
+
+        return {
+            # Basic state
+            "store": resolved_store,
+            "agents": agents,
+            "lock": lock,
+            "metrics": metrics,
+            "agent_iteration_count": agent_iteration_count,
+            # Engines
+            "artifact_collector": artifact_collector,
+            "correlation_engine": correlation_engine,
+            "batch_engine": batch_engine,
+            # Phase 5A modules
+            "context_builder": context_builder,
+            "event_emitter": event_emitter,
+            "lifecycle_manager": lifecycle_manager,
+            # Phase 3 modules
+            "mcp_manager_instance": mcp_manager_instance,
+            "tracing_manager": tracing_manager,
+            # Feature flags
+            "auto_workflow_enabled": auto_workflow_enabled,
+            # Placeholders
+            "websocket_manager": None,
+        }
+
+    @staticmethod
+    def initialize_components_and_runner(
+        components_list: list[OrchestratorComponent],
+        max_agent_iterations: int,
+        logger: logging.Logger,
+    ) -> dict[str, Any]:
+        """Initialize built-in components and create ComponentRunner.
+
+        Args:
+            components_list: List to populate with components
+            max_agent_iterations: Circuit breaker limit
+            logger: Logger instance
+
+        Returns:
+            Dictionary with component_runner and updated components list
+
+        Examples:
+            >>> components = []
+            >>> result = OrchestratorInitializer.initialize_components_and_runner(
+            ...     components, max_agent_iterations=1000, logger=logger
+            ... )
+            >>> component_runner = result["component_runner"]
+        """
+        from flock.components.orchestrator import (
+            BuiltinCollectionComponent,
+            CircuitBreakerComponent,
+            DeduplicationComponent,
+        )
+
+        # Add built-in components
+        components_list.append(
+            CircuitBreakerComponent(max_iterations=max_agent_iterations)
+        )
+        components_list.append(DeduplicationComponent())
+        components_list.append(BuiltinCollectionComponent())
+
+        # Sort by priority
+        components_list.sort(key=lambda c: c.priority)
+
+        # Create ComponentRunner
+        component_runner = ComponentRunner(components_list, logger)
+
+        return {
+            "component_runner": component_runner,
+        }