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

flock/orchestrator/component_runner.py

@@ -0,0 +1,389 @@
+"""Component lifecycle hook execution for orchestrator.
+
+This module manages the execution of OrchestratorComponent hooks in priority order.
+Components can modify artifacts, control scheduling decisions, and handle collection logic.
+"""
+
+from __future__ import annotations
+
+import logging
+from asyncio import Task
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    from flock.components.orchestrator import OrchestratorComponent
+    from flock.core import Agent
+    from flock.core.artifacts import Artifact
+    from flock.core.subscription import Subscription
+
+
+class ComponentRunner:
+    """Executes orchestrator component hooks in priority order.
+
+    This class manages the component lifecycle including initialization,
+    artifact processing, scheduling decisions, and shutdown. All hooks
+    execute in priority order (lower priority number = earlier execution).
+
+    Attributes:
+        _components: List of orchestrator components (sorted by priority)
+        _logger: Logger instance for component execution tracking
+        _initialized: Flag to prevent multiple initializations
+    """
+
+    def __init__(
+        self,
+        components: list[OrchestratorComponent],
+        logger: logging.Logger | None = None,
+    ) -> None:
+        """Initialize the component runner.
+
+        Args:
+            components: List of orchestrator components (should be pre-sorted by priority)
+            logger: Logger instance (defaults to module logger if not provided)
+        """
+        self._components = components
+        self._logger = logger or logging.getLogger(__name__)
+        self._initialized = False
+
+    @property
+    def components(self) -> list[OrchestratorComponent]:
+        """Get the list of registered components."""
+        return self._components
+
+    @property
+    def is_initialized(self) -> bool:
+        """Check if components have been initialized."""
+        return self._initialized
+
+    async def run_initialize(self, orchestrator: Any) -> None:
+        """Initialize all components in priority order (called once).
+
+        Executes on_initialize hook for each component. Sets _initialized
+        flag to prevent multiple initializations.
+
+        Args:
+            orchestrator: The Flock orchestrator instance
+        """
+        if self._initialized:
+            return
+
+        self._logger.info(
+            f"Initializing {len(self._components)} orchestrator components"
+        )
+
+        for component in self._components:
+            comp_name = component.name or component.__class__.__name__
+            self._logger.debug(
+                f"Initializing component: name={comp_name}, priority={component.priority}"
+            )
+
+            try:
+                await component.on_initialize(orchestrator)
+            except Exception as e:
+                self._logger.exception(
+                    f"Component initialization failed: name={comp_name}, error={e!s}"
+                )
+                raise
+
+        self._initialized = True
+        self._logger.info(f"All components initialized: count={len(self._components)}")
+
+    async def run_artifact_published(
+        self, orchestrator: Any, artifact: Artifact
+    ) -> Artifact | None:
+        """Run on_artifact_published hooks (returns modified artifact or None to block).
+
+        Components execute in priority order, each receiving the artifact from the
+        previous component (chaining). If any component returns None, the artifact
+        is blocked and scheduling stops.
+
+        Args:
+            orchestrator: The Flock orchestrator instance
+            artifact: The artifact being published
+
+        Returns:
+            Modified artifact or None if blocked by a component
+        """
+        current_artifact = artifact
+
+        for component in self._components:
+            comp_name = component.name or component.__class__.__name__
+            self._logger.debug(
+                f"Running on_artifact_published: component={comp_name}, "
+                f"artifact_type={current_artifact.type}, artifact_id={current_artifact.id}"
+            )
+
+            try:
+                result = await component.on_artifact_published(
+                    orchestrator, current_artifact
+                )
+
+                if result is None:
+                    self._logger.info(
+                        f"Artifact blocked by component: component={comp_name}, "
+                        f"artifact_type={current_artifact.type}, artifact_id={current_artifact.id}"
+                    )
+                    return None
+
+                current_artifact = result
+            except Exception as e:
+                self._logger.exception(
+                    f"Component hook failed: component={comp_name}, "
+                    f"hook=on_artifact_published, error={e!s}"
+                )
+                raise
+
+        return current_artifact
+
+    async def run_before_schedule(
+        self,
+        orchestrator: Any,
+        artifact: Artifact,
+        agent: Agent,
+        subscription: Subscription,
+    ) -> Any:
+        """Run on_before_schedule hooks (returns CONTINUE, SKIP, or DEFER).
+
+        Components execute in priority order. First component to return SKIP or
+        DEFER stops execution and returns that decision.
+
+        Args:
+            orchestrator: The Flock orchestrator instance
+            artifact: The artifact being scheduled
+            agent: The target agent
+            subscription: The subscription being evaluated
+
+        Returns:
+            ScheduleDecision (CONTINUE, SKIP, or DEFER)
+        """
+        from flock.components.orchestrator import ScheduleDecision
+
+        for component in self._components:
+            comp_name = component.name or component.__class__.__name__
+
+            self._logger.debug(
+                f"Running on_before_schedule: component={comp_name}, "
+                f"agent={agent.name}, artifact_type={artifact.type}"
+            )
+
+            try:
+                decision = await component.on_before_schedule(
+                    orchestrator, artifact, agent, subscription
+                )
+
+                if decision == ScheduleDecision.SKIP:
+                    self._logger.info(
+                        f"Scheduling skipped by component: component={comp_name}, "
+                        f"agent={agent.name}, artifact_type={artifact.type}, decision=SKIP"
+                    )
+                    return ScheduleDecision.SKIP
+
+                if decision == ScheduleDecision.DEFER:
+                    self._logger.debug(
+                        f"Scheduling deferred by component: component={comp_name}, "
+                        f"agent={agent.name}, decision=DEFER"
+                    )
+                    return ScheduleDecision.DEFER
+
+            except Exception as e:
+                self._logger.exception(
+                    f"Component hook failed: component={comp_name}, "
+                    f"hook=on_before_schedule, error={e!s}"
+                )
+                raise
+
+        return ScheduleDecision.CONTINUE
+
+    async def run_collect_artifacts(
+        self,
+        orchestrator: Any,
+        artifact: Artifact,
+        agent: Agent,
+        subscription: Subscription,
+    ) -> Any:
+        """Run on_collect_artifacts hooks (returns first non-None result).
+
+        Components execute in priority order. First component to return non-None
+        wins (short-circuit). If all return None, default is immediate scheduling.
+
+        Args:
+            orchestrator: The Flock orchestrator instance
+            artifact: The artifact being collected
+            agent: The target agent
+            subscription: The subscription being evaluated
+
+        Returns:
+            CollectionResult (complete=True/False, artifacts=[...])
+        """
+        from flock.components.orchestrator import CollectionResult
+
+        for component in self._components:
+            comp_name = component.name or component.__class__.__name__
+
+            self._logger.debug(
+                f"Running on_collect_artifacts: component={comp_name}, "
+                f"agent={agent.name}, artifact_type={artifact.type}"
+            )
+
+            try:
+                result = await component.on_collect_artifacts(
+                    orchestrator, artifact, agent, subscription
+                )
+
+                if result is not None:
+                    self._logger.debug(
+                        f"Collection handled by component: component={comp_name}, "
+                        f"complete={result.complete}, artifact_count={len(result.artifacts)}"
+                    )
+                    return result
+            except Exception as e:
+                self._logger.exception(
+                    f"Component hook failed: component={comp_name}, "
+                    f"hook=on_collect_artifacts, error={e!s}"
+                )
+                raise
+
+        # Default: immediate scheduling with single artifact
+        self._logger.debug(
+            f"No component handled collection, using default: "
+            f"agent={agent.name}, artifact_type={artifact.type}"
+        )
+        return CollectionResult.immediate([artifact])
+
+    async def run_before_agent_schedule(
+        self, orchestrator: Any, agent: Agent, artifacts: list[Artifact]
+    ) -> list[Artifact] | None:
+        """Run on_before_agent_schedule hooks (returns modified artifacts or None to block).
+
+        Components execute in priority order, each receiving artifacts from the
+        previous component (chaining). If any component returns None, scheduling
+        is blocked.
+
+        Args:
+            orchestrator: The Flock orchestrator instance
+            agent: The target agent
+            artifacts: List of artifacts to schedule
+
+        Returns:
+            Modified artifacts list or None if scheduling blocked
+        """
+        current_artifacts = artifacts
+
+        for component in self._components:
+            comp_name = component.name or component.__class__.__name__
+
+            self._logger.debug(
+                f"Running on_before_agent_schedule: component={comp_name}, "
+                f"agent={agent.name}, artifact_count={len(current_artifacts)}"
+            )
+
+            try:
+                result = await component.on_before_agent_schedule(
+                    orchestrator, agent, current_artifacts
+                )
+
+                if result is None:
+                    self._logger.info(
+                        f"Agent scheduling blocked by component: component={comp_name}, "
+                        f"agent={agent.name}"
+                    )
+                    return None
+
+                current_artifacts = result
+            except Exception as e:
+                self._logger.exception(
+                    f"Component hook failed: component={comp_name}, "
+                    f"hook=on_before_agent_schedule, error={e!s}"
+                )
+                raise
+
+        return current_artifacts
+
+    async def run_agent_scheduled(
+        self,
+        orchestrator: Any,
+        agent: Agent,
+        artifacts: list[Artifact],
+        task: Task[Any],
+    ) -> None:
+        """Run on_agent_scheduled hooks (notification only, non-blocking).
+
+        Components execute in priority order. Exceptions are logged but don't
+        prevent other components from executing or block scheduling.
+
+        Args:
+            orchestrator: The Flock orchestrator instance
+            agent: The scheduled agent
+            artifacts: List of artifacts for the agent
+            task: The asyncio task for agent execution
+        """
+        for component in self._components:
+            comp_name = component.name or component.__class__.__name__
+
+            self._logger.debug(
+                f"Running on_agent_scheduled: component={comp_name}, "
+                f"agent={agent.name}, artifact_count={len(artifacts)}"
+            )
+
+            try:
+                await component.on_agent_scheduled(orchestrator, agent, artifacts, task)
+            except Exception as e:
+                self._logger.warning(
+                    f"Component notification hook failed (non-critical): "
+                    f"component={comp_name}, hook=on_agent_scheduled, error={e!s}"
+                )
+                # Don't propagate - this is a notification hook
+
+    async def run_idle(self, orchestrator: Any) -> None:
+        """Run on_orchestrator_idle hooks when orchestrator becomes idle.
+
+        Components execute in priority order. Exceptions are logged but don't
+        prevent other components from executing.
+
+        Args:
+            orchestrator: The Flock orchestrator instance
+        """
+        self._logger.debug(
+            f"Running on_orchestrator_idle hooks: component_count={len(self._components)}"
+        )
+
+        for component in self._components:
+            comp_name = component.name or component.__class__.__name__
+
+            try:
+                await component.on_orchestrator_idle(orchestrator)
+            except Exception as e:
+                self._logger.warning(
+                    f"Component idle hook failed (non-critical): "
+                    f"component={comp_name}, hook=on_orchestrator_idle, error={e!s}"
+                )
+
+    async def run_shutdown(self, orchestrator: Any) -> None:
+        """Run on_shutdown hooks when orchestrator shuts down.
+
+        Components execute in priority order. Exceptions are logged but don't
+        prevent shutdown of other components (best-effort cleanup).
+
+        Args:
+            orchestrator: The Flock orchestrator instance
+        """
+        self._logger.info(
+            f"Shutting down {len(self._components)} orchestrator components"
+        )
+
+        for component in self._components:
+            comp_name = component.name or component.__class__.__name__
+            self._logger.debug(f"Shutting down component: name={comp_name}")
+
+            try:
+                await component.on_shutdown(orchestrator)
+            except Exception as e:
+                self._logger.exception(
+                    f"Component shutdown failed: component={comp_name}, "
+                    f"hook=on_shutdown, error={e!s}"
+                )
+                # Continue shutting down other components
+
+
+__all__ = ["ComponentRunner"]

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: