whiteducksoftware/flock

Flock is a Python-based orchestration framework for building and managing multi-agent workflows that communicate via a shared blackboard. It provides a modular engine system supporting various LLM providers, deterministic processing, and external tool integration through the Model Context Protocol. The system includes a comprehensive HTTP API and a real-time React dashboard for monitoring agent execution, visualizing workflow graphs, and managing artifacts.

85 changes.

The project was initialized with comprehensive scaffolding, establishing the core Flock orchestrator, agent builder APIs, and a blackboard-based workflow system. This period focused on building the foundational infrastructure, including a modular component architecture, extensive MCP transport support, and a real-time React dashboard for visualization. It also introduced critical subsystems for structured logging, OpenTelemetry tracing, and secure artifact management, alongside a robust suite of integration and unit tests.

6 changes.

This period focused on integrating the OpenClaw gateway into the Flock engine, adding support for streaming, structured outputs, and mixed-agent workflows. It also expanded the example suite with comprehensive demonstrations for Dapr-backed blackboard storage, including persistence and crash recovery scenarios.

New telemetry exporters have been added to the \src/flock/logging/telemetry\_exporter\ module, allowing OpenTelemetry spans to be persisted to local storage. Users can now export trace data to a DuckDB database (optimized for analytical queries with configurable TTL), an SQLite database, or a JSON Lines file via the new \DuckDBSpanExporter\, \SqliteTelemetryExporter\, and \FileSpanExporter\ classes, respectively. These components share a common \TelemetryExporter\ base class that standardizes the export and shutdown lifecycle.

_src/flock/logging/telemetry\exporter · high confidence

A new reference engine implementation, SimpleBatchEngine, is now available in the examples module. It demonstrates how to process inputs individually or in batches by auto-detecting the mode via the context's is\_batch flag, providing a concrete pattern for batch-aware evaluation in tutorials and tests.

src/flock/engines/examples · high confidence

Users can now connect to Model Context Protocol (MCP) servers using the Streamable HTTP transport. This change introduces a new client implementation (\FlockStreamableHttpClient\) and associated configuration classes (\FlockStreamableHttpConfig\, \FlockStreamableHttpConnectionConfig\) that enable communication with Streamable HTTP endpoints, including support for custom headers, authentication, timeouts, and session termination settings.

_src/flock/mcp/servers/streamable\http · high confidence

A new WebSocket server component has been introduced to enable real-time communication with the Flock Blackboard. This component registers a WebSocket endpoint (defaulting to /plugin/ws) that manages client connection lifecycles, including acceptance, heartbeat handling, and graceful disconnection. It integrates with the existing server architecture via a configurable prefix and tags, allowing clients to receive live dashboard events.

src/flock/components/server/websocket · high confidence

A new ServerComponent has been introduced to serve static files via FastAPI. Users can now configure a directory path and mount point to expose static assets, with the component automatically registering as a catch-all route at the root path.

_src/flock/components/server/static\files · high confidence

Users can now run local Hugging Face Transformers models directly through the Flock engine by using the 'transformers/' prefix in the model string (e.g., 'transformers/meta-llama/Llama-3.2-3B-Instruct'). This new provider integrates with LiteLLM to handle model loading, tokenization, and inference locally, requiring the 'transformers' and 'torch' libraries. The implementation includes a global model cache to avoid reloading models and supports automatic device placement via 'accelerate' when available.

src/flock/engines/providers · high confidence

Users can now connect to MCP servers using the Server-Sent Events (SSE) transport protocol. This change introduces the \FlockSSEClient\ and associated configuration classes (\FlockSSEConfig\, \FlockSSEConnectionConfig\) which enable establishing SSE connections with support for custom headers, timeouts, and authentication parameters.

src/flock/mcp/servers/sse · high confidence

Users can now connect to MCP servers via the standard input/output (stdio) transport. This change introduces a new \FlockStdioClient\ and associated configuration classes (\FlockStdioConfig\, \FlockStdioConnectionConfig\) within the \src/flock/mcp/servers/stdio\ module. The client wraps the underlying \mcp.stdio\_client\ to manage the connection lifecycle and allows runtime customization of server execution parameters such as command, arguments, environment variables, working directory, and encoding settings.

src/flock/mcp/servers/stdio · high confidence

Users can now connect to Model Context Protocol (MCP) servers using the WebSocket transport protocol. This change introduces a new \FlockWSClient\ implementation and associated configuration classes (\FlockWSConfig\, \FlockWSConnectionConfig\) within the \src/flock/mcp/servers/websockets\ module, enabling WebSocket-based communication alongside existing transport methods.

src/flock/mcp/servers/websockets · high confidence

A new health component has been introduced to the server, providing two new API endpoints: a /health endpoint that returns a JSON status of 'ok', and a /metrics endpoint that exposes raw Prometheus-style metrics from the orchestrator. This component is configurable via an optional URL prefix and custom tags, and is registered with high priority to ensure it is available early in the application lifecycle.

src/flock/components/server/health · high confidence

Added a series of Python example scripts in the examples/09-server-components directory demonstrating how to configure and use the Flock server components, including Authentication, CORS, Middleware, Health and Metrics, WebSocket, Artifacts, Agents, Control Routes, Static Files, Themes, and Tracing.

examples/09-server-components · high confidence

The examples/01-getting-started directory has been restructured to include a comprehensive suite of new demonstration scripts (01 through 14) that showcase advanced Flock capabilities. These examples introduce users to declarative agent definitions, complex multi-agent pipelines (such as band formation and news agency workflows), and conditional logic using where clauses (debate club). The updates also demonstrate practical integrations with external tools via the Model Context Protocol (MCP), including web search and filesystem access, as well as new orchestration features like JoinSpec for correlating multi-modal inputs (medical diagnostics) and BatchSpec for efficient batch processing (e-commerce). Additionally, the examples cover visibility controls for artifact security, unified execution tracing, and webhook notifications via the REST API.

examples/01-getting-started · high confidence

The frontend application now initializes via a new App component that bootstraps the dashboard by connecting to a WebSocket server (with configurable URL support for Codespaces and relative paths), loading historical artifact data and graph snapshots from the backend, and registering global keyboard shortcuts. The main entry point renders this App within a root element, and TypeScript environment declarations are added to support Vite-specific imports and build-time constants.

src/flock/frontend/src · high confidence

This change introduces the foundational type system and default callback handlers for the Flock MCP integration. It adds Pydantic models for server connection parameters (supporting stdio, websockets, SSE, and streamable HTTP transports) and defines specific notification types for logging, progress, resource updates, and tool list changes. Additionally, it provides factory functions and default implementations for handling incoming MCP requests, such as sampling, list roots, and logging messages, establishing the core communication layer for MCP servers.

src/flock/mcp/types · high confidence

The repository has been initialized with essential configuration files, including a Python version pin (3.12), pre-commit hooks for linting and security, a Git attributes file, and a comprehensive environment template (.envtemplate) for model and tracing configuration. Documentation has been added to guide contributors and AI agents, covering architecture, setup, and development workflows.

(repo-wide) · high confidence

The Flock Dashboard frontend has been added, providing a real-time visualization interface for monitoring and controlling Flock agent orchestration systems. Built with React, Vite, and TypeScript, the dashboard features dual visualization modes (Agent View and Blackboard View) with live WebSocket updates, interactive graph navigation, and auto-layout. It includes a Trace Viewer module for distributed tracing powered by OpenTelemetry and DuckDB, and a Historical Blackboard module for persisted artifact browsing. The UI utilizes a modern glassmorphism design with a dark theme, and the build configuration proxies API and WebSocket connections to the backend orchestrator on port 8344.

src/flock/frontend · high confidence

The repository now includes the Beads issue-tracking system, a CLI-first tool designed for AI coding agents and developers. This change adds the core configuration file (\.beads/config.yaml\), a \.gitignore\ to manage local runtime and database artifacts, and a \README.md\ with quick-start instructions. It also seeds the initial issue database (\.beads/issues.jsonl\) with a comprehensive set of closed tasks and epics related to the OpenClaw engine (including fan-out parity, multi-output envelopes, streaming support, and context/batch parity) and dashboard layout features, effectively establishing the project's planning and tracking baseline.

.beads · high confidence

Flock now supports connecting to external MCP servers, allowing agents to dynamically discover and use tools provided by those servers. This feature includes a client manager that handles connection pooling with per-agent and per-run isolation, lazy connection establishment, and automatic reconnection on transport timeouts. Tools are namespaced using the format {server}\\{tool} to prevent conflicts, and the integration supports multiple transport types including stdio, SSE, WebSockets, and Streamable HTTP. Configuration options allow for caching of tools and results, custom callbacks for sampling and logging, and specific mount points for server access.

src/flock/mcp · high confidence

Added the OpenClaw integration module, providing configuration models for gateway connections (including automatic token resolution from environment variables) and an engine component that delegates execution to an OpenClaw gateway via the /v1/responses API. The engine supports spawn-mode execution, structured output enforcement via JSON schemas, and Server-Sent Events (SSE) streaming for real-time output. It includes reliability counters for tracking parse, retry, and fallback metrics, and handles graceful fallbacks when the gateway rejects specific text formats.

src/flock/integrations · high confidence

This change establishes the foundational \src/flock/core\ module, introducing the \Flock\ orchestrator and \Agent\ builder APIs that coordinate blackboard-based agent workflows. It implements a mandatory security boundary via the \ContextProvider\ layer, which enforces visibility filtering to prevent agents from bypassing access controls. The update adds a Condition DSL (\Until\/\RunCondition\) for workflow termination and activation, supports semantic matching for subscriptions, and provides core types for fan-out, artifact storage, and visibility policies.

src/flock/core · high confidence

The flock package is now available, providing a Typer-based CLI for running demos and serving the HTTP control plane, a concrete demo orchestrator wiring agents for movie and tagline generation, and a runtime registry for blackboard artifact types and deterministic helper functions. The package also exposes a comprehensive public API with top-level imports for components, engines, conditions, and visibility, while automatically loading environment variables from .env files and registering optional LiteLLM providers when available.

src/flock · high confidence

Added a new TimerComponent in the orchestrator scheduling module that manages background tasks for agents with defined schedule specifications. The component initializes timer tasks for scheduled agents, calculates next fire times using croniter, and publishes TimerTick artifacts at configured intervals or specific times, while handling graceful shutdown and preventing duplicate task creation.

src/flock/components/orchestrator/scheduling · high confidence

Adds a new MiddlewareComponent that allows users to register and configure generic ASGI middleware via declarative configuration. Users can define a list of middlewares with specific names, options, and enabled states, which are applied to the server in the specified order (with the first middleware in the list becoming the outermost layer). This component supports both custom middleware factories and built-in Starlette middleware, providing a flexible way to extend server behavior without modifying core application code.

src/flock/components/server/middleware · high confidence

The server component library now provides a structured, modular approach to configuring the HTTP server. Users can now explicitly enable and configure core infrastructure via dedicated components: AuthenticationComponent allows registering custom auth handlers with global defaults and route-specific overrides; CORSComponent supports both global settings and granular, route-specific CORS policies; and base classes (ServerComponent, ServerComponentConfig) establish a standardized lifecycle (configure, register\_routes, startup/shutdown) with priority-based registration ordering. This change stabilizes the API for routing configuration by exposing these components through the main server package exports.

src/flock/components/server · high confidence

The server now exposes a structured set of Pydantic models to define its API contracts and internal data shapes. This includes request and response schemas for agent execution (e.g., \AgentRunRequest\, \AgentRunResponse\), detailed event models for the real-time dashboard (such as \AgentActivatedEvent\, \MessagePublishedEvent\, and \StreamingOutputEvent\), and comprehensive graph data structures for visualizing agent interactions and artifacts (including \GraphSnapshot\, \GraphNode\, and \GraphEdge\). These models standardize how agent lifecycle data, correlation statuses, and graph metrics are serialized and transmitted to clients.

src/flock/components/server/models · high confidence

The streaming engine now supports a modular sink pattern that allows streaming output from DSPy programs to be routed to multiple presentation layers simultaneously. This change introduces a \StreamSink\ protocol and specific implementations, including \RichSink\ for terminal updates and \WebSocketSink\ for dashboard broadcasting, enabling users to view live progress in the CLI while sending real-time updates to a web interface.

src/flock/engines/streaming · high confidence

The Flock orchestrator now exposes two new system data models to handle internal telemetry and scheduling. The \WorkflowError\ model captures details of agent failures (including the failed agent name, exception type, and message) to enable error tracking across workflows. Additionally, the \TimerTick\ model serves as an internal artifact published by the timer component to trigger scheduled agents, containing metadata such as the fire time, iteration count, and original schedule configuration. These models are defined using Pydantic and registered via the \@flock\_type\ decorator.

src/flock/models · high confidence

The server now exposes a new set of REST endpoints under the /api/v1/plugin/ prefix to interact with agents. Users can invoke an agent directly via POST /agents/{name}/run, retrieve a list of all available agents via GET /agents, view a summary of an agent's history with filtering options via GET /agents/{agent\_id}/history-summary, and check the status of a workflow by correlation ID via GET /correlations/{correlation\_id}/status.

src/flock/components/server/agents · high confidence

Introduced a new server component for managing artifacts, exposing endpoints under /api/v1/plugin/ to publish, list, and summarize artifacts. The API enforces a visibility model (Public, Private, Tenant, Labelled, and time-based AfterVisibility) to control access, resolving caller identity from request state or a configurable default. Responses include artifact metadata, consumption records, and pagination info, with support for filtering by type, producer, tags, visibility, and time range.

src/flock/components/server/artifacts · high confidence

The \src/flock/engines\ module now includes a new \DSPyEngine\ component that supports multi-output handling, fan-out evaluation, and configurable streaming with Rich display options (including a new 'crop\_above' overflow mode). It also introduces a new \lm\_kwargs\ field to pass provider-specific arguments and adds Azure authentication helpers (\get\_default\_azure\_token\_provider\) for seamless integration with Azure OpenAI and AI Foundry services.

src/flock/engines · high confidence

The examples/12-dapr directory now includes complete, runnable demonstrations for using Flock with a Dapr state store. This adds three pre-configured backend stacks—in-memory, encrypted Redis, and unencrypted PostgreSQL—each with its own Docker Compose setup, Dapr component definitions, and example Python scripts. Additionally, a new demos/ subdirectory provides two specific scenarios: crash recovery (verifying blackboard persistence after process restart) and shared blackboard usage (two Flock instances reading and writing to the same state store). These examples illustrate how to configure the DaprStateBlackboardStore, manage secrets via Dapr, and handle backend-specific constraints like encryption and transaction support.

examples/12-dapr · high confidence

Added nine new Python examples in the \examples/03-hackathon\ directory that showcase core Flock capabilities. These include basic agent definitions, multi-agent chains, conditional consumption with filters, fan-out publishing, semantic subscriptions for intelligent routing, timer scheduling, JoinSpec for correlating multiple artifact types, custom engines and components, and an MCP-based web researcher.

examples/03-hackathon · high confidence

The \src/flock/api\ package introduces a new HTTP control plane for the Flock orchestrator, built on FastAPI and uvicorn. It provides a composable \BaseHTTPService\ that registers \ServerComponent\ instances to manage routes, including a new synchronous publish endpoint with idempotency support (caching responses via \X-Idempotency-Key\ headers) and webhook notifications for artifact events (HMAC-signed delivery with retry logic). The package also adds a \DashboardLauncher\ to manage the frontend lifecycle (npm install, dev/production modes, browser launch), a \DashboardEventCollector\ to capture agent lifecycle events for real-time visualization, and a \GraphAssembler\ to build graph snapshots for the dashboard UI. Additionally, it includes a theme API endpoint that safely serves terminal color themes from TOML files.

src/flock/api · high confidence

Added six new Python examples in the examples/11-openclaw directory that demonstrate how to integrate OpenClaw agents into Flock workflows. The examples cover basic single-agent usage (01\_pizza\_with\_openclaw.py), mixed pipelines combining OpenClaw and native LLM agents (02\_mixed\_pipeline.py), environment-based gateway configuration (03\_env\_config.py), explicit streaming toggles for headless vs dashboard modes (04\_streaming\_on\_off.py), a complex competitive intelligence orchestration pipeline (05\_competitive\_intelligence.py), and a compact smoke test for fan-out and datetime handling (06\_fast\_orchestration\_smoke.py). A README.md provides setup instructions, configuration details, and documentation on the multi-output envelope contract and streaming behavior.

examples/11-openclaw · high confidence

A new PublishControl component has been added to the frontend, providing a slide-in panel that allows users to select an artifact type and submit content. The control dynamically renders form fields based on the artifact's JSON schema, supporting text, numbers, booleans, and arrays (represented as newline-separated lists). It handles default values from the schema, validates required fields and data types on the client side, and submits the data via the API.

src/flock/frontend/src/components/controls · high confidence

Users can now access two new modules via the module registry: a Trace Viewer (TraceModuleJaeger) that displays distributed traces with timeline, statistics, RED metrics, and dependency views, and a Historical Artifacts module (HistoricalArtifactsModule) that provides a browsable, filterable table of persisted artifacts with virtualized scrolling and a JSON attribute renderer. These modules are registered via registerModules.ts and rely on the new ModuleRegistry singleton for lifecycle management.

src/flock/frontend/src/components/modules · high confidence

A new TracingComponent has been added to the server, exposing API endpoints to query, view, and manage OpenTelemetry trace data stored in a local DuckDB database. Users can now retrieve trace spans, list unique traced services and operations, and access run and streaming history via the registered routes.

src/flock/components/server/traces · high confidence

The \scripts/\ directory now includes several new automation tools to support the project's build and release processes. \build\_dashboard.py\ copies frontend React artifacts into the Python package for serving, while \bump\_version.py\ and \check\_version\_bump.py\ provide smart, component-aware semantic versioning for the backend and frontend, including pre-push warnings. Additionally, \ensure\_uv.py\ validates the presence of the \uv\ tool, \gen\_ref\_pages.py\ automates API documentation generation, \generate\_llm\_codebase.py\ creates LLM-ready codebase exports, and \phase8\_file\_moves.sh\ along with \update\_imports.py\ facilitate the internal codebase reorganization by moving files and updating import paths.

scripts · high confidence

Added several new reusable components to the common library: BuildInfo for displaying build metadata, EmptyState for rendering empty content with optional actions, ErrorBoundary for catching and displaying React errors gracefully, KeyboardShortcutsDialog for showing a modal of available keyboard shortcuts, and LoadingSpinner for indicating loading states with configurable sizes and messages.

src/flock/frontend/src/components/common · high confidence

A new \src/flock/components\ package has been introduced to provide a structured library for extending Flock. This module exposes a comprehensive set of classes for agent components (including \AgentComponent\, \EngineComponent\, and the new \GuardComponent\ framework for input/output safety), orchestrator components (such as \OrchestratorComponent\, \DeduplicationComponent\, and \CircuitBreakerComponent\), and server components (including \AgentsServerComponent\, \ArtifactsComponent\, and \CORSComponent\). Users can now import these specific components to customize agent behavior, manage orchestration logic, and configure server capabilities.

src/flock/components · high confidence

Users now have access to a new, tabbed Settings panel that allows deep customization of the application's behavior and appearance. The Graph tab lets users adjust edge types (Bezier, Straight, etc.), stroke width, and toggle edge animations and labels. The Appearance tab provides controls for agent node colors (idle, active, error), node shadow intensity, status pulse animations, and a compact view mode, alongside a searchable selector for over 300 terminal themes. The Advanced tab exposes developer options like debug mode and performance mode (disabling animations), as well as manual graph layout controls for node/rank spacing and direction. Additionally, a new Tracing tab allows users to configure OpenTelemetry auto-tracing, manage service whitelists and operation blacklists, and view trace statistics.

src/flock/frontend/src/components/settings · high confidence

The application now features a new DashboardLayout component that introduces a view toggle allowing users to switch between 'Agent View' and 'Blackboard View'. The layout includes a header displaying the WebSocket connection status (Connected, Connecting, Reconnecting, Disconnected) with visual indicators and accessibility support. Additionally, the dashboard provides controls to toggle the visibility of the publish panel, agent detail windows, and settings panel, along with a clear data function that resets the graph, filters, and local storage.

src/flock/frontend/src/components/layout · high confidence

Users can now open floating, draggable, and resizable detail windows for individual graph nodes. Agent nodes display a Live Output tab that streams real-time tokens and logs via WebSocket (with history fetch on mount), a Message History tab showing consumed/published messages, and a Run Status tab for execution metrics. Message nodes display a dedicated window with metadata, payload, and consumption history. The DetailWindowContainer manages multiple concurrent windows, routing them to the correct component based on node type.

src/flock/frontend/src/components/details · high confidence

Added a new example in the complex patterns directory that illustrates three strategies for selecting the best output from multiple generated variations: a threshold filter, a two-stage selector, and LLM self-selection. This helps users understand how to handle scenarios where an agent produces N variations and only one specific artifact is needed downstream.

examples/02-patterns/complex-patterns · high confidence

Added new example scripts in the \examples/05-engines\ directory to demonstrate specific engine capabilities. \01\_adapter\_comparison.py\ compares ChatAdapter, JSONAdapter, BAMLAdapter, XMLAdapter, and TwoStepAdapter for structured output parsing. \02\_json\_adapter\_mcp\_tools.py\ shows how JSONAdapter enables native function calling for better integration with MCP tools. Additionally, \emoji\_mood\_engine.py\ and \potion\_batch\_engine.py\ provide examples of custom deterministic engines, including batch processing with auto-detection via \BatchSpec\.

examples/05-engines · high confidence

Added new example sketches in the \examples/app-sketches\ directory. The \github-project-starter\ example demonstrates an automated GitHub project workflow using the Flock framework, featuring agents that generate tasks, create repositories, and open issues via the GitHub MCP server, with support for both CLI and interactive dashboard modes. The \self-improving-workflow\ example introduces a semi-structured, phase-based agent system (Analysis, Implementation, Validation) where agents can dynamically discover and spawn new work across phases, enabling emergent, self-branching workflows. Both examples include comprehensive documentation, architecture guides, and runnable code snippets.

examples/app-sketches · high confidence

Added a new filter panel (FilterFlyout) and active filter indicators (FilterPills) to the frontend. The panel includes dedicated filters for Correlation ID, Time Range, Artifact Type, Producer, Tag, and Visibility, along with a SavedFiltersControl that allows users to save, apply, and delete filter presets using IndexedDB. FilterPills display active filters with the ability to remove them individually or toggle the filter panel visibility.

src/flock/frontend/src/components/filters · high confidence

The graph visualization area now includes dedicated components for rendering agent nodes (with OpenClaw badges and status styling), message nodes (showing JSON payloads and streaming text), and custom edges for message flows, pending joins, and pending batches. It also introduces displays for logic operations (JoinSpec/BatchSpec waiting states) and scheduled agents (timer countdowns and schedule details), along with a mini-map for navigation and comprehensive unit tests for the new node components.

src/flock/frontend/src/components/graph · high confidence

Users can now control the dashboard using global keyboard shortcuts (Ctrl/Cmd+M to toggle views, Ctrl/Cmd+F to focus filters, Ctrl/Cmd+, for settings, and others) via the new useKeyboardShortcuts hook. Module instances (such as event logs) are automatically persisted to IndexedDB, restoring their position, size, and visibility on reload with debounced saves during drag operations. The graph view now fetches a complete snapshot from the backend API (/api/dashboard/graph), merging backend node data with user-saved positions and real-time WebSocket state to ensure consistent layout and status display.

src/flock/frontend/src/services · high confidence

This location introduces a suite of new demonstration scripts: persistent artifact storage via SQLite (01\_persistent\_pizza.py, 04\_persistent\_pizza\_dashboard.py), advanced dashboard testing with conditional consumption and 100-agent scale stress tests (02-dashboard-edge-cases.py, 03-scale-test-100-agents.py), local model integration with LM Studio and Hugging Face Transformers (05\_lm\_studio.py, 08\_local\_transformers.py), Azure OpenAI authentication using DefaultAzureCredential (09\_azure\_default\_credential.py), structured logging configuration (07\_logging.py), and a comprehensive Product Requirements Document generation workflow (06\_prd.py).

examples/04-misc · high confidence

Added new example scripts in the \examples/07-orchestrator-components\ directory that demonstrate how to use \OrchestratorComponent\ to implement cross-cutting concerns across all agents. The \kitchen\_monitor\_component.py\ example shows how to track global metrics, issue real-time alerts (such as spice level warnings), and display performance dashboards for multiple agents. The \quest\_tracker\_component.py\ example illustrates how to maintain a global leaderboard and award achievement points based on quest difficulty and completion status across a multi-agent workflow.

examples/07-orchestrator-components · high confidence

The agent component now includes a new \GuardComponent\ framework that allows pluggable safety guards to scan agent inputs and outputs, with a built-in \AzurePromptShieldGuard\ implementation that detects jailbreak attacks and prompt injection via the Azure AI Content Safety REST API. The framework supports configurable actions (block, warn, annotate) for flagged content and integrates into the agent lifecycle via \on\_pre\_evaluate\ and \on\_post\_evaluate\ hooks. Additionally, the \OutputUtilityComponent\ now supports a \no\_output\ configuration option to suppress terminal output, useful for service mode operation.

src/flock/components/agent · high confidence

Added seven new Python examples in the publish section demonstrating the Flock framework's publishing capabilities. These include single and multi-publish workflows, static fan-out for generating multiple artifacts, and dynamic fan-out where the engine determines the number of outputs within a specified range (e.g., 3–10 milestones). The examples also showcase advanced features like filtering generated artifacts based on quality scores and integrating with DSPy and BAML engines for structured output parsing.

examples/02-patterns/publish · high confidence

Added a new example set in examples/08-semantic that demonstrates Flock's semantic subscription capabilities. The collection includes a verification script to test embedding and similarity features, an intelligent ticket routing example showing how agents can be routed based on semantic meaning rather than keywords, and a multi-criteria filtering example illustrating advanced patterns like field-specific matching, custom similarity thresholds, and hybrid semantic-structural filters.

examples/08-semantic · high confidence

A new ThemesComponent has been added to the server to expose theme configuration files via API endpoints. This component registers routes to list available themes (scanning for .toml files in a specified directory) and to retrieve the data for a specific theme by name. It includes basic path sanitization to prevent traversal attacks when loading theme files.

src/flock/components/server/themes · high confidence

A new \src/flock/utils\ package has been introduced to centralize common functionality across the Flock framework. This module provides an \AsyncLockRequired\ decorator to standardize async lock acquisition and prevent race conditions, a \TypeResolutionHelper\ to simplify type registry lookups, and an \ArtifactValidator\ for input validation. It also includes runtime envelope classes (\EvalInputs\, \EvalResult\) for structured data exchange between orchestrators and components, CLI helpers for displaying the Flock banner and managing console output, and time formatting utilities. These utilities are designed to replace duplicate patterns previously scattered across \orchestrator.py\, \agent.py\, and other core files.

src/flock/utils · high confidence

The \src/flock/logging\ module has been introduced to provide unified, structured logging and automatic distributed tracing. Users now get Rich-formatted console logs with color-coded categories and trace IDs, while the new \AutoTracedMeta\ metaclass and \@traced\_and\_logged\ decorator enable automatic OpenTelemetry span creation for method calls. Tracing is controlled via environment variables (e.g., \FLOCK\_AUTO\_TRACE\, \FLOCK\_TRACE\_SERVICES\) and supports multiple exporters including OTLP, Jaeger, file, SQLite, and DuckDB, with automatic configuration of logging levels and telemetry setup when auto-tracing is enabled.

src/flock/logging · high confidence

The logging formatters module now includes support for customizable visual themes. A new \themed\_formatter.py\ provides a Rich-based formatter that applies color palettes and layout styles to agent result logs, allowing users to switch between various pre-defined themes (such as Catppuccin, Monokai, and Solarized) defined in \themes.py\. To facilitate theme creation and customization, the module adds \theme\_builder.py\, an interactive tool for selecting palettes and generating TOML configuration files, and \enum\_builder.py\, which automatically generates the Python enum for available themes based on the theme folder contents.

src/flock/logging/formatters · high confidence

The examples/10-scheduling directory now includes six new Python scripts demonstrating Flock's timer scheduling capabilities. These examples cover interval-based monitoring (01\_simple\_health\_monitor.py), context-filtered log analysis (02\_error\_log\_analyzer.py), daily report generation (03\_daily\_report\_generator.py), batch data aggregation (04\_batch\_data\_processor.py), one-time reminders (05\_one\_time\_reminder.py), and cron-based execution (06\_cron\_demo.py). Each script illustrates how to use the .schedule() API for periodic, time-based, or cron triggers, and supports both CLI and interactive dashboard modes via the USE\_DASHBOARD flag.

examples/10-scheduling · high confidence

The frontend now includes dedicated TypeScript type definitions to support new UI capabilities. New files define the data structures for filter snapshots and saved filters (src/flock/frontend/src/types/filters.ts), the graph store backend integration including graph nodes, edges, and statistics (src/flock/frontend/src/types/graph.ts), module instance layout properties (src/flock/frontend/src/types/modules.ts), and terminal theme color configurations (src/flock/frontend/src/types/theme.ts). These types enable the UI to handle historical dashboard filters, graph visualization views, and theme customization.

src/flock/frontend/src/types · high confidence

Added three new utility files to the frontend codebase: \artifacts.ts\ provides a \mapArtifactToMessage\ function to transform API artifact list items into the internal Message format; \mockData.ts\ introduces legacy agent and message mock data structures along with an initialization function for testing or development environments; and \performance.ts\ exports helper functions to measure and log component render times using the browser Performance API.

src/flock/frontend/src/utils · high confidence

The orchestrator has been refactored into distinct modules to support advanced workflow patterns. Users can now define multi-type subscriptions that wait for multiple artifact types (AND gate logic) via the new ArtifactCollector, and correlate artifacts by key within time or count windows using the CorrelationEngine. Batch processing is now supported via BatchEngine, allowing agents to trigger on size thresholds or timeouts. Additionally, artifact publishing now validates dictionary inputs against registered models to prevent runtime errors, and a new \no\_output\ parameter allows suppressing all terminal output during initialization.

src/flock/orchestrator · high confidence

The agent implementation has been reorganized into distinct modules to improve modularity and reduce complexity. New helper classes (PublishBuilder, RunHandle, Pipeline) enable fluent API method chaining for agent configuration and sequential execution. A dedicated BuilderValidator provides warnings for feedback loop risks, excessive best\_of or concurrency values, and normalizes dict-based JoinSpec and BatchSpec configurations. Component lifecycle hooks (initialize, pre/post consume/evaluate, post publish, error, terminate) are now managed by a separate ComponentLifecycle class. Context resolution logic is extracted into ContextResolver, and MCP server configuration and tool loading are encapsulated in MCPIntegration with support for server-specific mounts and tool whitelists. Output processing, including validation, WHERE filtering, VALIDATE checks, and dynamic visibility, is handled by OutputProcessor.

src/flock/agent · high confidence

The Flock MCP utility layer now generates cache keys that incorporate function arguments, ensuring that cached results are distinct for different inputs. Previously, the cache key likely relied only on the agent and run identifiers, causing different arguments to return the same cached result. This change introduces a helper function that hashes the merged arguments and keyword arguments into the cache key, preventing stale or incorrect data from being served when the input parameters change.

src/flock/mcp/util · high confidence

The DSPy engine implementation has been restructured into modular components (SignatureBuilder, StreamingExecutor, ArtifactMaterializer) to improve maintainability. Users can now import common DSPy adapters (ChatAdapter, JSONAdapter, TwoStepAdapter, XMLAdapter, BAMLAdapter) directly from the flock namespace. The engine also supports dynamic fan-out for outputs and provides streaming execution via Rich CLI display or WebSocket-only mode for dashboard integration.

src/flock/engines/dspy · high confidence

This change introduces the \ControlRoutesComponent\ in the server control module, exposing new API endpoints under the \/api/plugin/\ prefix. The \/api/plugin/artifact\_types\ endpoint now returns registered artifact schemas, with a specific fix to hydrate array defaults from \default\_factory\ so the publish UI can correctly prefill list fields. Additionally, the \/api/plugin/agents\ endpoint has been enhanced to include detailed \logic\_operations\ data, exposing the current waiting state for agents using \JoinSpec\ or \BatchSpec\ by integrating with the \CorrelationEngine\ and \BatchEngine\ to report progress, timeouts, and collected items.

src/flock/components/server/control · high confidence

The frontend store layer has been restructured into a new set of Zustand-based stores (filterStore, graphStore, moduleStore, settingsStore, streamStore, uiStore, wsStore) that replace the previous client-side graph construction logic. The graphStore now consumes backend-generated snapshots instead of deriving edges and nodes locally, and the filterStore manages backend-driven filtering (correlation ID, time range, artifact types, producers, tags, visibility) that triggers graph refreshes. The uiStore introduces auto-layout toggles and position persistence, while the settingsStore centralizes UI, graph, appearance, and advanced configuration. Comprehensive test coverage has been added for all new stores.

src/flock/frontend/src/store · high confidence

The orchestrator logic in src/flock/components/orchestrator has been restructured into a modular component system, introducing base classes and lifecycle hooks for extensibility. This change adds an ActivationComponent that defers artifact scheduling until specific subscription conditions are met, a CircuitBreakerComponent to prevent runaway agent loops by limiting iterations, and a WebhookDeliveryComponent that sends notifications when artifacts are published. Existing orchestration behaviors like deduplication and artifact collection (AND gates, correlation, batching) are now implemented as prioritized components within this new framework.

src/flock/components/orchestrator · high confidence

The frontend static assets have been rebuilt with React 19.2.0, introducing new hooks such as useActionState and useEffectEvent, along with updated internal scheduling and hydration logic.

_src/flock/api/static\files · high confidence

The pre-commit hook that enforced commit message standards via commitlint has been removed. Users will no longer have their commit messages validated against conventional commit rules before commits are created.

.husky · high confidence

The storage package has been restructured to improve maintainability and reduce complexity. The main \\_\init\\.py\ files now use lazy imports via \\\getattr\\_\ to avoid circular dependencies and speed up startup. Storage-specific logic has been extracted into focused modules: Dapr serialization and client creation are separated into \\_serialization.py\ and \\_client.py\, while SQLite query building, schema management, and consumption loading are isolated in their own files. Additionally, artifact aggregation and filtering logic has been moved out of the main store classes into dedicated \ArtifactAggregator\, \ArtifactFilter\, and \HistoryAggregator\ utilities, making the core store implementations simpler and easier to test.

src/flock/storage · high confidence

The application now applies a monkey-patch to the DSPy library to prevent event-loop deadlocks when using MCP tools with dashboard streaming. The original DSPy implementation blocked the event loop while sending status messages; this change replaces that behavior with a non-blocking, fire-and-forget approach that schedules sends as background tasks, ensuring that tool callbacks complete without hanging the UI.

src/flock/patches · high confidence

Added API test coverage for sync publish, idempotency, themes, and webhooks; Added comprehensive server component tests; Added comprehensive test suite for SQLite storage modules; Added comprehensive test suites for agent builder, type normalization, and dashboard E2E scenarios; Added comprehensive tests for ServerManager; Added integration tests for OpenClaw pipeline and mixed-agent workflows; Added integration tests for graph snapshot consumption and IndexedDB persistence; Added integration tests for scheduled agents, async tool invocation, and event collection; Added localStorage mock for frontend tests; Added test coverage for utility modules; Added tests for ActivationComponent and WebhookDeliveryComponent; Added tests for Logic Operations API state extraction and WebSocket event emission; Added tests for agent component lifecycle, context resolution, MCP integration, and output processing; Added tests for core condition DSL and orchestrator lifecycle; Added tests for in-memory storage filtering and history aggregation; Added tests for semantic subscription and context features; Added tests for storage module exports and artifact aggregation; Added unit tests for Dapr storage client, serialization, and blackboard store helpers.

The project's Python dependencies have been updated, including major version bumps for DSPy (to 3.2.1) and LiteLLM (to 1.96.2), alongside updates to FastAPI, Starlette, and various OpenTelemetry components. The frontend has been migrated from Yarn to npm, introducing React 19, Vite 7, and Vitest 3, while removing the legacy template package.json and yarn.lock files.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 57 → 55 (-2.1)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 75 → 72 (-3.0)
• Architecture 90 → 88 (-2.5)
• Maturity 72 → 79 (+7.8)
• Readiness 51 → 46 (-4.3)
• Security 60 → 61 (+1.1)
• Accessibility 56 → 54 (-1.8)

• 01_fan_out_selection.main_cli (cognitive 25) (examples/02-patterns/complex-patterns/01_fan_out_selection.py)
• Coverage not included — suite not readable by the collector
• Critical CVE: [GHSA redacted] (requirements.txt)
• Critical CVE: [GHSA redacted] (src/flock/frontend/package-lock.json)
• Critical CVE: [GHSA redacted] (uv.lock)
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• Duplicated block (10 lines × 2) (examples/01-getting-started/05_mcp_and_tools.py)
• Duplicated block (10 lines × 2) (src/flock/components/server/traces/trace_component.py)
• Duplicated block (10 lines × 2) (src/flock/engines/dspy/signature_builder.py)
• Duplicated block (11 lines × 2) (examples/05-engines/01_adapter_comparison.py)
• Duplicated block (11 lines × 2) (src/flock/core/store.py)
• Duplicated block (11 lines × 2) (src/flock/engines/dspy/streaming_executor.py)
• Duplicated block (11 lines × 2) (src/flock/logging/formatters/theme_builder.py)
• Duplicated block (11 lines × 2) (src/flock/storage/dapr/dapr_state_blackboard_store.py)
• Duplicated block (11 lines × 2) (src/flock/storage/dapr/dapr_state_blackboard_store.py)
• Duplicated block (12 lines × 2) (examples/02-patterns/visibility/01_basic_visibility.py)
• Duplicated block (12 lines × 2) (examples/05-engines/potion_batch_engine.py)
• Duplicated block (12 lines × 2) (src/flock/api/service.py)
• Duplicated block (12 lines × 2) (src/flock/engines/dspy/signature_builder.py)
• Duplicated block (12 lines × 2) (src/flock/logging/trace_and_logged.py)
• …and 85 more

• AgentNode.AgentNode (cognitive 46) (src/flock/frontend/src/components/graph/AgentNode.tsx)
• AgentNode.AgentNode (cyclomatic 58) (src/flock/frontend/src/components/graph/AgentNode.tsx)
• App.App (cognitive 31) (src/flock/frontend/src/App.tsx)
• App.App (cyclomatic 19) (src/flock/frontend/src/App.tsx)
• ClassTooLong: GraphCanvas (src/flock/frontend/src/components/graph/GraphCanvas.tsx)
• ClassTooLong: IndexedDBService (src/flock/frontend/src/services/indexeddb.ts)
• ClassTooLong: PublishControl (src/flock/frontend/src/components/controls/PublishControl.tsx)
• ClassTooLong: TraceModuleJaeger (src/flock/frontend/src/components/modules/TraceModuleJaeger.tsx)
• ClassTooLong: WebSocketClient (src/flock/frontend/src/services/websocket.ts)
• Context.fire_time (cognitive 25) (src/flock/utils/runtime.py)
• Critical CVE: [GHSA redacted] (uv.lock)
• Critical CVE: [GHSA redacted] (requirements.txt)
• Critical CVE: [GHSA redacted] (uv.lock)
• DashboardLayout.DashboardLayout (cognitive 21) (src/flock/frontend/src/components/layout/DashboardLayout.tsx)
• DashboardLayout.DashboardLayout (cyclomatic 20) (src/flock/frontend/src/components/layout/DashboardLayout.tsx)
• Documentation: no installation or build instructions (README.md)
• Documentation: no installation or build instructions (docs/index.md)
• Documentation: no installation or build instructions (examples/01-getting-started/README.md)
• Documentation: no project overview (README.md)
• Documentation: no usage examples (docs/index.md)
• …and 226 more

• 31 commits — 11 feature/other, 20 fixes

• (repo) — 11 commits
• src/flock — 9 commits
• (root) — 7 commits
• examples/12-dapr — 4 commits

• fix: Merge branch 'main' into dependabot-246-jupyter-server-fix
• fix: Merge pull request #420 from whiteducksoftware/dependabot-176-vitest-fix
• fix: Merge pull request #421 from whiteducksoftware/dependabot-246-jupyter-server-fix
• fix: Merge pull request #424 from whiteducksoftware/fix/rest-publish-correlation-id
• fix: Merge pull request #425 from whiteducksoftware/fix/artifacts-component-correlation-id
• fix: Merge pull request #426 from whiteducksoftware/fix/visibility-ci-and-correlation
• fix: Merge pull request #453 from whiteducksoftware/fix/427-remove-trace-sql
• fix: chore: prepare 0.5.610 bugfix release
• fix: fix(api): carry the REST correlation id on the artifact; tolerate consumptions without one; apply external log level to dspy/litellm
• fix: fix(ci): restore green test suite for frontend and dapr helpers
• fix: fix(deps): update jupyter-server for Dependabot alert 246
• fix: fix(frontend): update Vitest for Dependabot alert 176
• fix: fix(orchestrator): partition multi-type waiting pools by correlation_id
• fix: fix(orchestrator): resolve simple type names on dict publish; harden Dapr example stacks
• fix: fix(orchestrator): validate dict publishes against the registered model
• fix: fix(server): ArtifactsComponent publishes carry a correlation id; consumption records may lack one
• fix: fix(server): enforce artifact visibility model on HTTP endpoints (#417)
• fix: fix: harden artifact API visibility
• fix: fix: remove arbitrary trace SQL from HTTP and dashboard
• fix: fix: update LiteLLM for security patches
• …and 11 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

whiteducksoftware/flock was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.