flock-core 0.5.8__py3-none-any.whl → 0.5.10__py3-none-any.whl

flock/orchestrator.py

@@ -95,6 +95,7 @@ class Flock(metaclass=AutoTracedMeta):
         *,
         store: BlackboardStore | None = None,
         max_agent_iterations: int = 1000,
+        context_provider: Any = None,
     ) -> None:
         """Initialize the Flock orchestrator for blackboard-based agent coordination.
 
@@ -104,32 +105,43 @@ class Flock(metaclass=AutoTracedMeta):
             store: Custom blackboard storage backend. Defaults to InMemoryBlackboardStore.
             max_agent_iterations: Circuit breaker limit to prevent runaway agent loops.
                 Defaults to 1000 iterations per agent before reset.
+            context_provider: Global context provider for all agents (Phase 3 security fix).
+                If None, agents use DefaultContextProvider. Can be overridden per-agent.
 
         Examples:
             >>> # Basic initialization with default model
             >>> flock = Flock("openai/gpt-4.1")
 
             >>> # Custom storage backend
-            >>> flock = Flock(
-            ...     "openai/gpt-4o",
-            ...     store=CustomBlackboardStore()
-            ... )
+            >>> flock = Flock("openai/gpt-4o", store=CustomBlackboardStore())
 
             >>> # Circuit breaker configuration
+            >>> flock = Flock("openai/gpt-4.1", max_agent_iterations=500)
+
+            >>> # Global context provider (Phase 3 security fix)
+            >>> from flock.context_provider import DefaultContextProvider
             >>> flock = Flock(
-            ...     "openai/gpt-4.1",
-            ...     max_agent_iterations=500
+            ...     "openai/gpt-4.1", context_provider=DefaultContextProvider()
             ... )
         """
         self._patch_litellm_proxy_imports()
         self._logger = logging.getLogger(__name__)
         self.model = model
+
+        try:
+            init_console(clear_screen=True, show_banner=True, model=self.model)
+        except (UnicodeEncodeError, UnicodeDecodeError):
+            # Skip banner on Windows consoles with encoding issues (e.g., tests, CI)
+            pass
+
         self.store: BlackboardStore = store or InMemoryBlackboardStore()
         self._agents: dict[str, Agent] = {}
         self._tasks: set[Task[Any]] = set()
         self._processed: set[tuple[str, str]] = set()
         self._lock = asyncio.Lock()
         self.metrics: dict[str, float] = {"artifacts_published": 0, "agent_runs": 0}
+        # Phase 3: Global context provider (security fix)
+        self._default_context_provider = context_provider
         # MCP integration
         self._mcp_configs: dict[str, FlockMCPConfiguration] = {}
         self._mcp_manager: FlockMCPClientManager | None = None
@@ -153,7 +165,9 @@ class Flock(metaclass=AutoTracedMeta):
         self._websocket_manager: Any = None
         # Unified tracing support
         self._workflow_span = None
-        self._auto_workflow_enabled = os.getenv("FLOCK_AUTO_WORKFLOW_TRACE", "false").lower() in {
+        self._auto_workflow_enabled = os.getenv(
+            "FLOCK_AUTO_WORKFLOW_TRACE", "false"
+        ).lower() in {
             "true",
             "1",
             "yes",
@@ -357,7 +371,11 @@ class Flock(metaclass=AutoTracedMeta):
                     path_str = str(abs_path)
 
                 # Extract a meaningful name (last component of path)
-                name = PathLib(path_str).name or path_str.rstrip("/").split("/")[-1] or "root"
+                name = (
+                    PathLib(path_str).name
+                    or path_str.rstrip("/").split("/")[-1]
+                    or "root"
+                )
                 mcp_roots.append(MCPRoot(uri=uri, name=name))
 
         # Build configuration
@@ -559,12 +577,17 @@ class Flock(metaclass=AutoTracedMeta):
         if pending_batches and (
             self._batch_timeout_task is None or self._batch_timeout_task.done()
         ):
-            self._batch_timeout_task = asyncio.create_task(self._batch_timeout_checker_loop())
+            self._batch_timeout_task = asyncio.create_task(
+                self._batch_timeout_checker_loop()
+            )
 
         if pending_correlations and (
-            self._correlation_cleanup_task is None or self._correlation_cleanup_task.done()
+            self._correlation_cleanup_task is None
+            or self._correlation_cleanup_task.done()
         ):
-            self._correlation_cleanup_task = asyncio.create_task(self._correlation_cleanup_loop())
+            self._correlation_cleanup_task = asyncio.create_task(
+                self._correlation_cleanup_loop()
+            )
 
         # If deferred work is still outstanding, consider the orchestrator quiescent for
         # now but leave watchdog tasks running to finish the job.
@@ -585,15 +608,60 @@ class Flock(metaclass=AutoTracedMeta):
     async def direct_invoke(
         self, agent: Agent, inputs: Sequence[BaseModel | Mapping[str, Any] | Artifact]
     ) -> list[Artifact]:
-        artifacts = [self._normalize_input(value, produced_by="__direct__") for value in inputs]
+        artifacts = [
+            self._normalize_input(value, produced_by="__direct__") for value in inputs
+        ]
         for artifact in artifacts:
             self._mark_processed(artifact, agent)
             await self._persist_and_schedule(artifact)
-        ctx = Context(board=BoardHandle(self), orchestrator=self, task_id=str(uuid4()))
+
+        # Phase 8: Evaluate context BEFORE creating Context (security fix)
+        # Provider resolution: per-agent > global > DefaultContextProvider
+        from flock.context_provider import (
+            BoundContextProvider,
+            ContextRequest,
+            DefaultContextProvider,
+        )
+
+        inner_provider = (
+            getattr(agent, "context_provider", None)
+            or self._default_context_provider
+            or DefaultContextProvider()
+        )
+
+        # SECURITY FIX: Wrap provider with BoundContextProvider to prevent identity spoofing
+        provider = BoundContextProvider(inner_provider, agent.identity)
+
+        # Evaluate context using provider (orchestrator controls this!)
+        # Engines will receive pre-filtered artifacts via ctx.artifacts
+        correlation_id = (
+            artifacts[0].correlation_id
+            if artifacts and artifacts[0].correlation_id
+            else uuid4()
+        )
+        request = ContextRequest(
+            agent=agent,
+            correlation_id=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)
+
+        # Phase 8: Create Context with pre-filtered data (no capabilities!)
+        # SECURITY: Context is now just data - engines can't query anything
+        ctx = Context(
+            artifacts=context_artifacts,  # Pre-filtered conversation context
+            agent_identity=agent.identity,
+            task_id=str(uuid4()),
+            correlation_id=correlation_id,
+        )
         self._record_agent_run(agent)
         return await agent.execute(ctx, artifacts)
 
-    async def arun(self, agent_builder: AgentBuilder, *inputs: BaseModel) -> list[Artifact]:
+    async def arun(
+        self, agent_builder: AgentBuilder, *inputs: BaseModel
+    ) -> list[Artifact]:
         """Execute an agent with inputs and wait for all cascades to complete (async).
 
         Convenience method that combines direct agent invocation with run_until_idle().
@@ -614,9 +682,7 @@ class Flock(metaclass=AutoTracedMeta):
 
             >>> # Multiple inputs
             >>> results = await flock.arun(
-            ...     task_agent,
-            ...     Task(name="deploy"),
-            ...     Task(name="test")
+            ...     task_agent, Task(name="deploy"), Task(name="test")
             ... )
 
         Note:
@@ -735,6 +801,15 @@ class Flock(metaclass=AutoTracedMeta):
         # Store websocket manager for real-time event emission (Phase 1.2)
         self._websocket_manager = websocket_manager
 
+        # Phase 6+7: Set class-level WebSocket broadcast wrapper (dashboard mode)
+        async def _broadcast_wrapper(event):
+            """Isolated broadcast wrapper - no reference chain to orchestrator."""
+            return await websocket_manager.broadcast(event)
+
+        from flock.agent import Agent
+
+        Agent._websocket_broadcast_global = _broadcast_wrapper
+
         # Inject event collector into all existing agents
         for agent in self._agents.values():
             # Add dashboard collector with priority ordering handled by agent
@@ -802,21 +877,12 @@ class Flock(metaclass=AutoTracedMeta):
 
             >>> # Publish with custom visibility
             >>> await orchestrator.publish(
-            ...     task,
-            ...     visibility=PrivateVisibility(agents={"admin"})
+            ...     task, visibility=PrivateVisibility(agents={"admin"})
             ... )
 
             >>> # Publish with tags for channel routing
             >>> await orchestrator.publish(task, tags={"urgent", "backend"})
         """
-        self.is_dashboard = is_dashboard
-        # Only show banner in CLI mode, not dashboard mode
-        if not self.is_dashboard:
-            try:
-                init_console(clear_screen=True, show_banner=True, model=self.model)
-            except (UnicodeEncodeError, UnicodeDecodeError):
-                # Skip banner on Windows consoles with encoding issues (e.g., tests, CI)
-                pass
         # Handle different input types
         if isinstance(obj, Artifact):
             # Already an artifact - publish as-is
@@ -925,16 +991,12 @@ class Flock(metaclass=AutoTracedMeta):
         Examples:
             >>> # Testing: Execute agent without triggering others
             >>> results = await orchestrator.invoke(
-            ...     agent,
-            ...     Task(name="test", priority=5),
-            ...     publish_outputs=False
+            ...     agent, Task(name="test", priority=5), publish_outputs=False
             ... )
 
             >>> # HTTP endpoint: Execute specific agent, allow cascade
             >>> results = await orchestrator.invoke(
-            ...     movie_agent,
-            ...     Idea(topic="AI", genre="comedy"),
-            ...     publish_outputs=True
+            ...     movie_agent, Idea(topic="AI", genre="comedy"), publish_outputs=True
             ... )
             >>> await orchestrator.run_until_idle()
         """
@@ -953,8 +1015,42 @@ class Flock(metaclass=AutoTracedMeta):
             visibility=PublicVisibility(),
         )
 
-        # Execute agent directly
-        ctx = Context(board=BoardHandle(self), orchestrator=self, task_id=str(uuid4()))
+        # Phase 8: Evaluate context BEFORE creating Context (security fix)
+        # Provider resolution: per-agent > global > DefaultContextProvider
+        from flock.context_provider import (
+            BoundContextProvider,
+            ContextRequest,
+            DefaultContextProvider,
+        )
+
+        inner_provider = (
+            getattr(agent_obj, "context_provider", None)
+            or self._default_context_provider
+            or DefaultContextProvider()
+        )
+
+        # SECURITY FIX: Wrap provider with BoundContextProvider to prevent identity spoofing
+        provider = BoundContextProvider(inner_provider, agent_obj.identity)
+
+        # Evaluate context using provider (orchestrator controls this!)
+        correlation_id = artifact.correlation_id if artifact.correlation_id else uuid4()
+        request = ContextRequest(
+            agent=agent_obj,
+            correlation_id=correlation_id,
+            store=self.store,
+            agent_identity=agent_obj.identity,
+            exclude_ids={artifact.id},  # Exclude input artifact
+        )
+        context_artifacts = await provider(request)
+
+        # Phase 8: Create Context with pre-filtered data (no capabilities!)
+        # SECURITY: Context is now just data - engines can't query anything
+        ctx = Context(
+            artifacts=context_artifacts,  # Pre-filtered conversation context
+            agent_identity=agent_obj.identity,
+            task_id=str(uuid4()),
+            correlation_id=correlation_id,
+        )
         self._record_agent_run(agent_obj)
 
         # Execute with optional timeout
@@ -964,7 +1060,8 @@ class Flock(metaclass=AutoTracedMeta):
         else:
             outputs = await agent_obj.execute(ctx, [artifact])
 
-        # Optionally publish outputs to blackboard
+        # Phase 6: Orchestrator publishes outputs (security fix)
+        # Agents return artifacts, orchestrator validates and publishes
         if publish_outputs:
             for output in outputs:
                 await self._persist_and_schedule(output)
@@ -987,7 +1084,9 @@ class Flock(metaclass=AutoTracedMeta):
         if self._components_initialized:
             return
 
-        self._logger.info(f"Initializing {len(self._components)} orchestrator components")
+        self._logger.info(
+            f"Initializing {len(self._components)} orchestrator components"
+        )
 
         for component in self._components:
             comp_name = component.name or component.__class__.__name__
@@ -1061,7 +1160,9 @@ class Flock(metaclass=AutoTracedMeta):
             )
 
             try:
-                decision = await component.on_before_schedule(self, artifact, agent, subscription)
+                decision = await component.on_before_schedule(
+                    self, artifact, agent, subscription
+                )
 
                 if decision == ScheduleDecision.SKIP:
                     self._logger.info(
@@ -1105,7 +1206,9 @@ class Flock(metaclass=AutoTracedMeta):
             )
 
             try:
-                result = await component.on_collect_artifacts(self, artifact, agent, subscription)
+                result = await component.on_collect_artifacts(
+                    self, artifact, agent, subscription
+                )
 
                 if result is not None:
                     self._logger.debug(
@@ -1147,7 +1250,9 @@ class Flock(metaclass=AutoTracedMeta):
             )
 
             try:
-                result = await component.on_before_agent_schedule(self, agent, current_artifacts)
+                result = await component.on_before_agent_schedule(
+                    self, agent, current_artifacts
+                )
 
                 if result is None:
                     self._logger.info(
@@ -1218,7 +1323,9 @@ class Flock(metaclass=AutoTracedMeta):
         Components execute in priority order. Exceptions are logged but don't
         prevent shutdown of other components (best-effort cleanup).
         """
-        self._logger.info(f"Shutting down {len(self._components)} orchestrator components")
+        self._logger.info(
+            f"Shutting down {len(self._components)} orchestrator components"
+        )
 
         for component in self._components:
             comp_name = component.name or component.__class__.__name__
@@ -1271,14 +1378,18 @@ class Flock(metaclass=AutoTracedMeta):
                 # Phase 3: Component hook - before schedule (circuit breaker, deduplication, etc.)
                 from flock.orchestrator_component import ScheduleDecision
 
-                decision = await self._run_before_schedule(artifact, agent, subscription)
+                decision = await self._run_before_schedule(
+                    artifact, agent, subscription
+                )
                 if decision == ScheduleDecision.SKIP:
                     continue  # Skip this subscription
                 if decision == ScheduleDecision.DEFER:
                     continue  # Defer for later (batching/correlation)
 
                 # Phase 3: Component hook - collect artifacts (handles AND gates, correlation, batching)
-                collection = await self._run_collect_artifacts(artifact, agent, subscription)
+                collection = await self._run_collect_artifacts(
+                    artifact, agent, subscription
+                )
                 if not collection.complete:
                     continue  # Still collecting (AND gate, correlation, or batch incomplete)
 
@@ -1292,7 +1403,9 @@ class Flock(metaclass=AutoTracedMeta):
                 # Complete! Schedule agent with collected artifacts
                 # Schedule agent task
                 is_batch_execution = subscription.batch is not None
-                task = self._schedule_task(agent, artifacts, is_batch=is_batch_execution)
+                task = self._schedule_task(
+                    agent, artifacts, is_batch=is_batch_execution
+                )
 
                 # Phase 3: Component hook - agent scheduled (notification)
                 await self._run_agent_scheduled(agent, artifacts, task)
@@ -1301,7 +1414,9 @@ class Flock(metaclass=AutoTracedMeta):
         self, agent: Agent, artifacts: list[Artifact], is_batch: bool = False
     ) -> Task[Any]:
         """Schedule agent task and return the task handle."""
-        task = asyncio.create_task(self._run_agent_task(agent, artifacts, is_batch=is_batch))
+        task = asyncio.create_task(
+            self._run_agent_task(agent, artifacts, is_batch=is_batch)
+        )
         self._tasks.add(task)
         task.add_done_callback(self._tasks.discard)
         return task
@@ -1322,15 +1437,52 @@ class Flock(metaclass=AutoTracedMeta):
     ) -> None:
         correlation_id = artifacts[0].correlation_id if artifacts else uuid4()
 
+        # Phase 8: Evaluate context BEFORE creating Context (security fix)
+        # Provider resolution: per-agent > global > DefaultContextProvider
+        from flock.context_provider import (
+            BoundContextProvider,
+            ContextRequest,
+            DefaultContextProvider,
+        )
+
+        inner_provider = (
+            getattr(agent, "context_provider", None)
+            or self._default_context_provider
+            or DefaultContextProvider()
+        )
+
+        # SECURITY FIX: Wrap provider with BoundContextProvider to prevent identity spoofing
+        provider = BoundContextProvider(inner_provider, agent.identity)
+
+        # Evaluate context using provider (orchestrator controls this!)
+        # Engines will receive pre-filtered artifacts via ctx.artifacts
+        request = ContextRequest(
+            agent=agent,
+            correlation_id=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)
+
+        # Phase 8: Create Context with pre-filtered data (no capabilities!)
+        # SECURITY: Context is now just data - engines can't query anything
         ctx = Context(
-            board=BoardHandle(self),
-            orchestrator=self,
+            artifacts=context_artifacts,  # Pre-filtered conversation context
+            agent_identity=agent.identity,
             task_id=str(uuid4()),
             correlation_id=correlation_id,
-            is_batch=is_batch,  # NEW!
+            is_batch=is_batch,
         )
         self._record_agent_run(agent)
-        await agent.execute(ctx, artifacts)
+
+        # Phase 6: Execute agent (returns artifacts, doesn't publish)
+        outputs = await agent.execute(ctx, artifacts)
+
+        # Phase 6: Orchestrator publishes outputs (security fix)
+        # This fixes Vulnerability #2 (WRITE Bypass) - agents can't bypass validation
+        for output in outputs:
+            await self._persist_and_schedule(output)
 
         if artifacts:
             try:
@@ -1373,7 +1525,9 @@ class Flock(metaclass=AutoTracedMeta):
         from flock.dashboard.service import _get_correlation_groups
 
         # Get current correlation groups state from engine
-        groups = _get_correlation_groups(self._correlation_engine, agent_name, subscription_index)
+        groups = _get_correlation_groups(
+            self._correlation_engine, agent_name, subscription_index
+        )
 
         if not groups:
             return  # No groups to report (shouldn't happen, but defensive)

flock/orchestrator_component.py

@@ -150,7 +150,9 @@ class OrchestratorComponent(BaseModel, metaclass=TracedModelMeta):
         >>> # Simple component
         >>> class LoggingComponent(OrchestratorComponent):
         ...     async def on_agent_scheduled(self, orch, agent, artifacts, task):
-        ...         print(f"Agent {agent.name} scheduled with {len(artifacts)} artifacts")
+        ...         print(
+        ...             f"Agent {agent.name} scheduled with {len(artifacts)} artifacts"
+        ...         )
 
         >>> # Circuit breaker component
         >>> class CircuitBreakerComponent(OrchestratorComponent):
@@ -166,7 +168,9 @@ class OrchestratorComponent(BaseModel, metaclass=TracedModelMeta):
     """
 
     name: str | None = None
-    config: OrchestratorComponentConfig = Field(default_factory=OrchestratorComponentConfig)
+    config: OrchestratorComponentConfig = Field(
+        default_factory=OrchestratorComponentConfig
+    )
     priority: int = 0  # Lower priority = earlier execution
 
     # ──────────────────────────────────────────────────────────
@@ -355,7 +359,7 @@ class OrchestratorComponent(BaseModel, metaclass=TracedModelMeta):
             ...     await self.ws.broadcast({
             ...         "event": "agent_scheduled",
             ...         "agent": agent.name,
-            ...         "count": len(artifacts)
+            ...         "count": len(artifacts),
             ...     })
         """
 
@@ -484,7 +488,10 @@ class BuiltinCollectionComponent(OrchestratorComponent):
                     subscription_index=subscription_index,
                 )
 
-                if subscription.batch.timeout and orchestrator._batch_timeout_task is None:
+                if (
+                    subscription.batch.timeout
+                    and orchestrator._batch_timeout_task is None
+                ):
                     import asyncio
 
                     orchestrator._batch_timeout_task = asyncio.create_task(
@@ -500,7 +507,10 @@ class BuiltinCollectionComponent(OrchestratorComponent):
                         subscription_index=subscription_index,
                     )
 
-                    if subscription.batch.timeout and orchestrator._batch_timeout_task is None:
+                    if (
+                        subscription.batch.timeout
+                        and orchestrator._batch_timeout_task is None
+                    ):
                         import asyncio
 
                         orchestrator._batch_timeout_task = asyncio.create_task(

flock/patches/dspy_streaming_patch.py

@@ -45,7 +45,9 @@ def patched_sync_send_to_stream(stream, message):
         try:
             asyncio.run(_send())
         except Exception as e:
-            logger.debug(f"DSPy status message send failed in sync context (non-critical): {e}")
+            logger.debug(
+                f"DSPy status message send failed in sync context (non-critical): {e}"
+            )
 
 
 def apply_patch():
@@ -55,12 +57,16 @@ def apply_patch():
 
         # Store original for reference (in case we need to restore)
         if not hasattr(dspy_messages, "_original_sync_send_to_stream"):
-            dspy_messages._original_sync_send_to_stream = dspy_messages.sync_send_to_stream
+            dspy_messages._original_sync_send_to_stream = (
+                dspy_messages.sync_send_to_stream
+            )
 
         # Replace with our non-blocking version
         dspy_messages.sync_send_to_stream = patched_sync_send_to_stream
 
-        logger.info("Applied DSPy streaming patch - status messages are now non-blocking")
+        logger.info(
+            "Applied DSPy streaming patch - status messages are now non-blocking"
+        )
         return True
 
     except Exception as e:
@@ -74,7 +80,9 @@ def restore_original():
         import dspy.streaming.messages as dspy_messages
 
         if hasattr(dspy_messages, "_original_sync_send_to_stream"):
-            dspy_messages.sync_send_to_stream = dspy_messages._original_sync_send_to_stream
+            dspy_messages.sync_send_to_stream = (
+                dspy_messages._original_sync_send_to_stream
+            )
             logger.info("Restored original DSPy streaming function")
             return True
 

flock/registry.py

@@ -25,9 +25,13 @@ class TypeRegistry:
 
     def register(self, model: type[BaseModel], name: str | None = None) -> str:
         if not issubclass(model, BaseModel):
-            raise RegistryError("Only Pydantic models can be registered as artifact types.")
+            raise RegistryError(
+                "Only Pydantic models can be registered as artifact types."
+            )
         type_name = (
-            name or getattr(model, "__flock_type__", None) or f"{model.__module__}.{model.__name__}"
+            name
+            or getattr(model, "__flock_type__", None)
+            or f"{model.__module__}.{model.__name__}"
         )
         existing_model = self._by_name.get(type_name)
         if existing_model is not None and existing_model is not model:
@@ -127,7 +131,9 @@ def flock_type(model: type[BaseModel] | None = None, *, name: str | None = None)
     return _wrap(model)
 
 
-def flock_tool(func: Callable[..., Any] | None = None, *, name: str | None = None) -> Any:
+def flock_tool(
+    func: Callable[..., Any] | None = None, *, name: str | None = None
+) -> Any:
     """Decorator to register a deterministic helper function for agents."""
 
     def _wrap(callable_: Callable[..., Any]) -> Callable[..., Any]: