Skip to content
CAI
Software that uses CAICheck a score

whiteducksoftware/flock

59.4

Adequate · 10 November 2026

74.8k

lines of production code

Python

with TypeScript

9

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

Features

Add OpenTelemetry span exporters for DuckDB, SQLite, and JSON files

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

Add SimpleBatchEngine example implementation

A new example engine, SimpleBatchEngine, is now available in the flock engines examples module. This reference implementation allows users to explore or adapt a simple batch processing engine pattern within the flock framework.

src/flock/engines/examples · high confidence

Add Streamable HTTP client support for MCP servers

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

Add WebSocket component for real-time dashboard events

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

Add static file serving component

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

Added SSE server transport support

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

Added Stdio transport support for MCP servers

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

Added WebSocket transport support for MCP clients

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

Added health and metrics endpoints to the server

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 semantic subscription examples and verification script

Added a new example directory (examples/08-semantic) demonstrating semantic subscription features, including intelligent ticket routing and multi-criteria filtering based on semantic similarity rather than keywords. Included a verification script (00\_verify\_semantic\_features.py) to test embedding generation, similarity computation, batch processing, and caching without requiring LLM API calls, along with comprehensive documentation (README.md) covering prerequisites, usage patterns, and performance metrics.

examples/08-semantic · high confidence

Added server component usage examples

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

DSPy engine modularized with image input support and adapter re-exports

The DSPy engine implementation has been restructured into modular components (SignatureBuilder, StreamingExecutor, ArtifactMaterializer) to improve maintainability. This change introduces support for multimodal inputs, allowing LLM agents to receive flock.Image fields as actual images via dspy.Image conversion, and ensures computed image fields are correctly sent. Additionally, common DSPy adapters (Chat, JSON, TwoStep, XML, BAML) are now re-exported through the flock namespace for easier access, and streaming error handling has been improved to surface failures more clearly in both CLI and dashboard modes.

src/flock/engines/dspy · high confidence

Frontend application entry points and configuration established

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

Host Flock applications as Microsoft Foundry agents

Users can now deploy Flock applications as hosted agents on Microsoft Foundry using the new \flock-core\[foundry\]\ integration. This adds the \FoundryResponsesAdapter\, which maps Foundry's Responses protocol to Flock's execution API, supporting conversation history, custom input/output mappers, and identity policies. Example code is provided for running Flock in plain workers and via custom ASGI services (Starlette/SSE) to demonstrate the underlying transport-independent execution model.

examples/13-applications, src/flock/integrations/foundry · high confidence

Initial MCP type definitions and callback infrastructure

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

Initial project scaffolding and configuration

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

Initial release of the Flock Dashboard frontend

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

Initialize Beads AI-native issue tracking in the repository

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

Introduce Dapr-backed blackboard storage implementation

Adds a new storage backend for the Flock blackboard that persists state using Dapr State Store components. This includes the core store implementation, configuration models, a thin wrapper for the Dapr gRPC client, and JSON serialization helpers for artifacts, consumption records, and agent snapshots. A README is also added to point users to canonical documentation.

src/flock/storage/dapr · high confidence

Introduce FlockApplication for transport-independent workflow execution

A new FlockApplication API is added to src/flock/application, providing a transport-independent way to run typed workflows from any host (such as ASGI endpoints, queue workers, or Microsoft Foundry). Users can now build a FlockApplication from a factory, define input/output contracts, and execute workflows with streaming outputs and explicit lifecycle management, decoupling the core Flock engine from specific hosting frameworks.

src/flock/application · high confidence

Introduce MCP (Model Context Protocol) integration for dynamic tool discovery

Flock-Flow 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 graceful degradation if a server fails. Users can register MCP servers (supporting stdio, SSE, WebSocket, and Streamable HTTP transports) and enable them for specific agents, with tools automatically namespaced as {server}\\{tool}. The implementation also includes caching for tools and results, configurable retry logic, and support for server-side callbacks like logging and sampling.

src/flock/mcp · high confidence

Introduce OpenClaw integration with spawn-mode execution and SSE streaming

Users can now connect Flock to OpenClaw gateways via a new integration module. The OpenClawEngine delegates agent execution to the OpenClaw \/v1/responses\ API in spawn mode, supporting structured JSON-schema output contracts and graceful fallbacks when the gateway rejects text formatting. Configuration is managed through \GatewayConfig\ and \OpenClawConfig\ models, which automatically resolve authentication tokens from environment variables (e.g., \OPENCLAW\_\<ALIAS\>\_TOKEN\) and store them securely using \SecretStr\. The integration also includes Server-Sent Events (SSE) streaming support for real-time output in the dashboard and CLI, along with reliability counters to track parse, retry, and fallback metrics.

src/flock/integrations/openclaw · high confidence

Introduce flock package with CLI, demo orchestrator, and artifact registry

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

Introduces configurable middleware component for server

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

Introduces modular server component architecture with authentication and CORS support

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

Introduction of composable streaming sink architecture

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

Introduction of core Flock orchestrator and security-enforced context provider

The \src/flock/core\ module now provides the foundational abstractions for the Flock framework, including the \Flock\ orchestrator, \Agent\ definitions, and the \BoardHandle\ for artifact management. A critical addition is the \ContextProvider\ layer, which acts as a mandatory security boundary between agents and the blackboard store, enforcing visibility filtering to prevent read/write bypasses and unauthorized access. The orchestrator initialization has been modularized via \OrchestratorInitializer\, and the module exposes key components like \OpenClawConfig\ and \GatewayConfig\ for integration.

src/flock/core · high confidence

Introduction of timer-based agent scheduling component

A new scheduling module has been added to the orchestrator, exposing a TimerComponent that enables timer-based execution of agents. This change introduces the initial scheduling infrastructure, allowing agents to be triggered on a schedule rather than solely on demand.

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

New 'Getting Started' example suite for flock-core

Added a comprehensive set of 14 new examples in the \examples/01-getting-started/\ directory to demonstrate core Flock capabilities. These include declarative agent definitions, input/output handling, MCP integration with tools and roots, multi-agent pipelines, debate workflows with conditional subscriptions, webhook notifications, visibility controls, and advanced subscription patterns like JoinSpec and BatchSpec.

flock-core · high confidence

New Agents API endpoints for running and inspecting agents

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

New DSPy engine with Azure authentication and streaming enhancements

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

New Dapr-backed Blackboard examples and crash-recovery demos

The \examples/12-dapr\ area now includes ready-to-run Docker Compose stacks for three state-store backends—In-memory, Redis (encrypted), and PostgreSQL 17—along with a \demos/\ directory that demonstrates crash recovery and shared blackboards across two Flock processes. These examples show how to plug any Dapr-supported backend into Flock's Blackboard via \DaprStateBlackboardStore\, enabling distributed state, encryption at rest, and TTL-based expiration without changing agent code.

examples/12-dapr · high confidence

New HTTP API service layer with REST endpoints and dashboard infrastructure

This change introduces the \src/flock/api\ package, establishing the core HTTP control plane for the Flock orchestrator. It adds a \BaseHTTPService\ that composes \ServerComponent\s into a FastAPI application, enabling modular route registration. The package includes a \DashboardEventCollector\ to capture agent lifecycle events for real-time visualization, a \GraphAssembler\ to build dashboard graph snapshots from the blackboard store, and a \DashboardLauncher\ to manage the frontend npm lifecycle. REST capabilities are expanded with an idempotency layer for safe retries, image upload handling with format validation and re-encoding, and a themes API. The \BlackboardHTTPService\ registers public API endpoints for publishing artifacts (with webhook support and named runs), querying agents and artifacts, and managing agent runs, all backed by Pydantic models for OpenAPI documentation.

src/flock/api · high confidence

New Trace Viewer and Historical Artifacts modules

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

New Tracing API component for viewing agent execution traces

A new TracingComponent has been added to the server, exposing API endpoints to query and view OpenTelemetry trace data stored in a local DuckDB database. This allows users to inspect agent execution details, including span hierarchies, timing, and attributes, via endpoints such as /api/traces. The component handles database connection configuration and provides the underlying data structure for trace visualization.

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

New artifact management component with visibility enforcement and thumbnail support

Introduces the ArtifactsComponent, a new server module that exposes REST endpoints for managing artifacts, including publishing, listing, and retrieving consumption history. The component enforces a visibility model (public, private, tenant, labelled) on HTTP endpoints and supports image thumbnails generated off the event loop to prevent blocking. It also handles artifact uploads while preserving visibility, tags, and partition keys, and allows clients to name runs via correlation\_id.

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

New build, versioning, and refactoring automation scripts

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

New common UI components and build info display

This change introduces a suite of reusable UI components to the common library: an ErrorBoundary for graceful error handling with reset/reload options, an EmptyState component for displaying empty data scenarios with optional actions, an ImageThumbnails component that previews artifact images and opens them in a modal dialog on demand, a LoadingSpinner with size variants and accessibility support, a KeyboardShortcutsDialog for displaying platform-specific shortcuts, and a BuildInfo component that displays the current build hash and timestamp for deployment verification.

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

New component library for extending Flock agents, orchestrators, and server

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

New comprehensive settings panel with granular customization options

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

New dashboard layout with view toggle and connection status header

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

New decision model examples and documentation

Added a new \examples/15-decisions\ directory featuring a comprehensive README and supporting data files (arXiv abstracts, compliance controls, and documents) that demonstrate how to use decision models for typed questions, workflow routing, and compliance checking. The examples showcase key concepts such as \Choice\, \YesNo\, \Scale\, and \Checklist\ types, including a ticket triage scenario, an LLM vs. decision model race on arXiv abstracts, a color sorter using image-capable models, multi-question decisions, and a compliance checklist against 100 controls. The data files provide the necessary ground truth and context for these examples to run and report on model performance.

examples/15-decisions · high confidence

New decision model system with typed questions, human review, and dashboard integration

The \src/flock/decisions\ module introduces a new capability for agents to make decisions based on typed questions (Choice, YesNo, Scale, and Checklist) against input artifacts. This system includes a decision engine that handles request budgets, shadow modes for model comparison, and escalation cascades. It supports human review, allowing users to confirm or override AI decisions, and integrates with the dashboard to visualize decision nodes, option-labelled edges, and decision artifacts. The module also provides routing logic to deliver decision subjects to subscribed agents and graph data for dashboard visualization.

src/flock/decisions · high confidence

New detail windows for agent and message nodes

The details panel now supports floating, draggable, and resizable windows for both agent and message nodes. Agent nodes display a Live Output tab (streaming tokens and logs via WebSocket with history fetch), a Message History tab, and a Run Status tab (showing run timing, token usage, and cost, including handling for unpriced models and active runs without a duration). Message nodes display a dedicated window showing artifact metadata, payload, and consumption history. A new DetailWindowContainer manages multiple open windows, routing them to the correct component based on node type.

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

New filter UI components and saved presets support

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

New graph visualization components for the dashboard

The dashboard now includes a new set of components in the graph area to visualize the system's agent and message flows. This adds an AgentNode component that displays agent status, subscriptions, and decision details (including options, counts, and image thumbnails), as well as a MessageNode component for viewing artifacts, decisions, and explanations. It also introduces specialized edge types like MessageFlowEdge, PendingJoinEdge, and PendingBatchEdge to represent different data flows and waiting states, along with supporting displays for logic operations and decision artifacts.

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

New keyboard shortcuts, module persistence, and backend-integrated graph service

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

New optional semantic matching for artifact retrieval

Flock now includes an optional semantic matching feature that allows agents to retrieve historical artifacts based on semantic similarity to a query. This capability is provided by the new \flock/semantic\ module, which introduces an \EmbeddingService\ (using the \all-MiniLM-L6-v2\ model via \sentence-transformers\) and a \SemanticContextProvider\. Users can enable this by installing the \\[semantic\]\ extra (\uv add flock-core\[semantic\]\). If the extra is not installed, the system gracefully degrades, leaving core functionality unaffected. The context provider allows filtering by artifact type, applying custom predicates, and specifying a similarity threshold (default 0.4) and result limit.

src/flock/semantic · high confidence

New pluggable safety guard framework and Azure Prompt Shield integration

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

New server component for serving theme files

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

New shared utility module for the Flock framework

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

New storage module structure and histogram logic

The storage package has been reorganized into a modular structure with lazy-loaded exports for Dapr and SQLite backends. A new histogram module provides precise, microsecond-based bucketing for artifact activity timelines, ensuring consistent distribution across stores and separately tracking workflow errors. Additionally, an artifact aggregator utility has been added to compute summary statistics such as type distribution, producer counts, and time ranges for dashboard reports.

src/flock/storage · high confidence

New structured logging and OpenTelemetry tracing system

Flock introduces a new logging and telemetry subsystem in \src/flock/logging\ that integrates Rich for formatted console output and OpenTelemetry for distributed tracing. Users can now enable automatic tracing via the \FLOCK\_AUTO\_TRACE\ environment variable, which configures log levels and initializes telemetry exporters (OTLP, file, SQLite, or DuckDB) based on environment settings. The system supports trace context propagation through HTTP headers, allowing external requests to continue existing traces. Tracing is configurable via \FLOCK\_TRACE\_LEVEL\ (defaulting to 'agents' to trace agent work, or 'all' to include internals) and \FLOCK\_TRACE\_MAX\_ATTRIBUTE\_BYTES\ to cap span attribute sizes. The logging system provides structured logs with trace IDs and color-coded categories, and automatically handles image data description in spans to reduce payload size.

src/flock/logging · high confidence

New theme-aware logging formatters and theme management tools

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

New type definitions for filtering, graph visualization, and theming

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

New utility modules for image handling, artifact mapping, and performance monitoring

This change introduces several new utility files in the frontend utils directory. \imageFields.ts\ and its tests provide logic to identify image fields within JSON schemas, convert files to scaled data URLs (dropping metadata like GPS), and determine output types for transparency support. \artifacts.ts\ adds a mapper to convert API artifact list items into the internal Message format used by the graph. \performance.ts\ introduces helpers to mark and measure component render times using the Performance API. Additionally, \mockData.ts\ provides legacy mock data for agents and messages, primarily for testing purposes.

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

Orchestrator modularization and new artifact correlation/batching capabilities

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

Publish panel now supports image uploads and array field defaults

The PublishControl component now allows users to upload images (single or multiple) which are converted to data URLs and included in the published artifact, handling race conditions where image conversions finish late or are replaced by newer selections. Additionally, the panel correctly hydrates array fields from their schema defaults (e.g., pre-filling lists of strings or numbers) and respects required/nullable constraints for these fields.

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

Behavioural changes

Agent module refactored into modular components with builder helpers and validation

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

MCP caching now includes function arguments in cache keys

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

New control routes API for agent state and artifact schemas

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

New frontend state management architecture with backend-driven graph filtering

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

Orchestrator refactored into extensible component system with activation, circuit breaking, and webhook notifications

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

Removal of commit message linting hook

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

SQLite storage backend modularized into focused query and schema components

The SQLite storage implementation has been restructured to improve maintainability and testability. The monolithic store logic is now split into specialized modules: \SQLiteQueryBuilder\ and \SQLiteConsumptionLoader\ handle safe, parameterized artifact filtering and consumption loading; \AgentHistoryQueries\ and \SQLiteSummaryQueries\ manage specific aggregation queries for agent history and artifact statistics; \QueryParamsBuilder\ standardizes pagination logic; and \SQLiteSchemaManager\ centralizes database schema creation, versioning, and migration (upgrading to version 4). An in-memory equivalent structure with \ArtifactFilter\ and \HistoryAggregator\ has also been introduced to support the same modular patterns for non-persistent storage.

src/flock/storage/sqlite · high confidence

Fixes

Fixes dashboard streaming deadlocks with MCP tools

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

Test coverage

Added API test coverage for decision review, image handling, and sync publishing; Added comprehensive test suite for SQLite storage modules; Added comprehensive test suites for agent builder, type normalization, and dashboard E2E scenarios; 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 orchestrator test coverage for publication listeners, scheduler outcomes, server management, shutdown, and workflow scopes; Added server component tests for active runs, artifact consumption, histograms, visibility, and core infrastructure; 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 tests for the decision subsystem; Added unit tests for Dapr storage client, serialization, and blackboard store helpers.

Dependencies

Core and frontend dependency updates

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 cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

How this codebase got here

Score

  • CAI 57 → 59 (+2.0)
  • Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.

Lenses

  • Code Health 60 → 60 (+0.1)
  • Architecture 81 → 80 (-1.1)
  • Maturity 57 → 87 (+30.7)
  • Readiness 56 → 63 (+6.6)
  • Security 55 → 56 (+1.1)
  • Accessibility 58 → 56 (-2.5)
  • Performance 100 → 100 (+0.0)

Resolved (21)

  • ADR has no Consequences section (openspec/changes/archive/2026-02-17-openclaw-multi-output-envelope/design.md)
  • Ambiguous intent of 'execute'. In RunHandle, execute likely triggers the actual agent run. In Pipeline, execute likely triggers the entire chain. While technically distinct scopes, the method name is identical. If RunHandle is a component of a Pipeline, the naming is consistent. However, RunHandle also has then, suggesting a builder pattern, while Pipeline also has then. The duplication of then and execute on both types suggests they might be interchangeable or one is a wrapper for the other, creating confusion about whether to use the Handle or the Pipeline for execution.
  • Critical CVE: [GHSA redacted] (uv.lock)
  • Critical vulnerability: [GHSA redacted] (uv.lock)
  • Duplicate lifecycle hook interfaces. ComponentLifecycle and AgentComponent expose nearly identical lifecycle methods (run_* vs on_*) with the same signatures and intent (pre/post consume, evaluate, publish, error, terminate). This creates two parallel ways to hook into the agent lifecycle, confusing users about which interface to implement.
  • Duplicated block (30 lines × 2) (src/flock/logging/trace_and_logged.py)
  • High CVE: [GHSA redacted] (uv.lock)
  • High CVE: [GHSA redacted] (uv.lock)
  • High CVE: [GHSA redacted] (uv.lock)
  • High secret: WD-SECRET-0005 (examples/08-context-provider/05_password_redactor.py)
  • High vulnerability: [GHSA redacted] (uv.lock)
  • Leaked secret: hardcoded-credential (examples/12-dapr/postgresql_unencrypted/docker-compose.yml)
  • Leaked secret: signing-key (examples/12-dapr/demos/_common.py)
  • Medium CVE: [GHSA redacted] (uv.lock)
  • Medium CVE: [GHSA redacted] (src/flock/frontend/package-lock.json)
  • Medium CVE: [GHSA redacted] (uv.lock)
  • Redundant naming for synchronous/asynchronous execution. The distinction between run and run_async is implicit in the name but explicit in the signature only by convention (or lack of return type). It is more consistent to use start/start_async or serve/serve_async to clearly indicate lifecycle management rather than execution style, or to have a single start method that handles both via a parameter.
  • Rotate the exposed credentials — git history can't be un-committed
  • Secret: generic-api-key (examples/11-openclaw/01_pizza_with_openclaw.py)
  • VersionBumper.bump_versions (cognitive 19) (scripts/bump_version.py)
  • …and 1 more

New (34)

  • Duplicated block (31 lines × 2) (src/flock/logging/trace_and_logged.py)
  • High CVE: [GHSA redacted] (uv.lock)
  • Medium CVE: [GHSA redacted] (uv.lock)
  • Orphaned file (src/flock/storage/dapr/init.py)
  • Repeated repair: src/flock/logging/auto_trace.py (src/flock/logging/auto_trace.py)
  • CorrelationIDFilter spells ID where 40 names in the project spell it Id (src/flock/frontend/src/components/filters/CorrelationIDFilter.tsx)
  • genai_spans.output_messages (cognitive 16) (src/flock/logging/genai_spans.py)
  • redundant comment (docs/javascripts/extra.js)
  • redundant comment (docs/javascripts/extra.js)
  • redundant comment (src/flock/frontend/src/tests/integration/graph-snapshot.test.tsx)
  • redundant comment (src/flock/frontend/src/tests/integration/graph-snapshot.test.tsx)
  • redundant comment (src/flock/frontend/src/tests/integration/graph-snapshot.test.tsx)
  • redundant comment (src/flock/frontend/src/tests/integration/graph-snapshot.test.tsx)
  • redundant comment (src/flock/frontend/src/tests/integration/indexeddb-persistence.test.tsx)
  • redundant comment (src/flock/frontend/src/components/controls/PublishControl.tsx)
  • redundant comment (src/flock/frontend/src/components/details/LiveOutputTab.tsx)
  • redundant comment (src/flock/frontend/src/components/details/MessageDetailWindow.tsx)
  • redundant comment (src/flock/frontend/src/components/details/tabs.test.tsx)
  • redundant comment (src/flock/frontend/src/components/details/tabs.test.tsx)
  • redundant comment (src/flock/frontend/src/components/graph/AgentNode.tsx)
  • …and 14 more

Changes since last survey

  • 31 commits — 21 feature/other, 10 fixes

By area

  • docs/assets — 10 commits
  • (repo) — 7 commits
  • src/flock — 6 commits
  • (root) — 4 commits
  • docs/guides — 3 commits
  • docs/about — 1 commit

Notable commits

  • fix: Merge pull request #677 from whiteducksoftware/fix/676-security-deps
  • fix: Merge pull request #684 from whiteducksoftware/fix/679-otlp-http
  • fix: Merge pull request #690 from whiteducksoftware/fix/689-security-deps
  • fix: fix: Responses API usage and the conventions' message schema (#680, review round 1)
  • fix: fix: close the 113 Dependabot alerts on main (#676)
  • fix: fix: close the litellm and dnspython Dependabot alerts on main (#689)
  • fix: fix: export OTLP over HTTP when the OTel variables ask for it (#679)
  • fix: fix: one span per call for nested agents, Responses API tool calls (#680, review round 2)
  • fix: fix: only a context names the run, a payload field does not (#681, review round 1)
  • fix: fix: the run comes from the bound ctx or a Context, never a payload (#681, review round 2)
  • change: Merge pull request #686 from whiteducksoftware/feat/680-genai-spans
  • change: Merge pull request #687 from whiteducksoftware/feat/681-session-id
  • change: Merge pull request #688 from whiteducksoftware/docs/682-tracing-backends
  • change: Merge pull request #691 from whiteducksoftware/chore/bump-0.5.800
  • change: chore: bump version to 0.5.800
  • change: docs: README screenshot for the PR of #682 (removed in the next commit)
  • change: docs: a guide for tracing backends, comparisons without claims about other tools (#682)
  • change: docs: exported spans carry tokens, backends estimate the cost (#682, review round 1)
  • change: docs: one more screenshot for the PR of #680 (removed in the next commit)
  • change: docs: portable base64 for the Langfuse header (#682, review round 2)
  • …and 11 more

Architecture

  • Unchanged — 0 containers · 1 contexts · 0 edges

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

Survey your own repository

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.

About this page

  • The score is its most recent published measurement, taken on 10 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
  • Measured at commit 63ff5ab64220f63049dcc3c954f312e876d9b915 — the exact code this score is about.
  • Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
  • Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.4+preprod-464a0040a931.